From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: AS3215 2.6.0.0/16 X-Spam-Status: No, score=-3.4 required=3.0 tests=AWL,BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,SPF_HELO_NONE, SPF_PASS,T_SCC_BODY_TEXT_LINE shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from out1.vger.email (out1.vger.email [IPv6:2620:137:e000::1:20]) by dcvr.yhbt.net (Postfix) with ESMTP id A9B801F727 for ; Tue, 28 Jun 2022 20:17:17 +0000 (UTC) Authentication-Results: dcvr.yhbt.net; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="XUAJnHvx"; dkim-atps=neutral Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229578AbiF1UNE (ORCPT ); Tue, 28 Jun 2022 16:13:04 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49724 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229742AbiF1ULz (ORCPT ); Tue, 28 Jun 2022 16:11:55 -0400 Received: from mail-wr1-x42b.google.com (mail-wr1-x42b.google.com [IPv6:2a00:1450:4864:20::42b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 4CABE9B for ; Tue, 28 Jun 2022 13:03:02 -0700 (PDT) Received: by mail-wr1-x42b.google.com with SMTP id q9so19245977wrd.8 for ; Tue, 28 Jun 2022 13:03:02 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:in-reply-to:references:from:date:subject:fcc :content-transfer-encoding:mime-version:to:cc; bh=f+QoN/nzrShfmtBkPJa6F8B6fGZKUS6q6/ntopxepgw=; b=XUAJnHvxOdpx1SWSauZRen60TN4khnvu3Dt7bX6zfFTh7uEEQUaVGsuUmDR078hZPU zsTABeCG/lMWtmau20giVlODE8Oz8LD1LzoHKlXX6QCN/NMr5v9XMkV+JSiaoU6qGv0J 12DhGc3kx1yISllelAOKqPURFXY47K7stffGeAaKZsa0aXSZFwfvA1t7+Pii3fGyGnbJ kRo+coEUmcqi6wPwmEP2IoQDxR/g/MuDGaPLI/eo/dYm0be1fmCcSnvl0RCvNuArNKvY dNUQmO8MWdjsYXeK1ETl9C0no0YJ5BcpIQoHuUjn7MHBmXOMDhWoIFAfcLm96Jto1YuC E6mw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:in-reply-to:references:from:date :subject:fcc:content-transfer-encoding:mime-version:to:cc; bh=f+QoN/nzrShfmtBkPJa6F8B6fGZKUS6q6/ntopxepgw=; b=l0k/B8fnZpBTc8RHZ74UCeeIoybIT8339VFzqiQZkUd8MRGqTDBf9yGuola0vVckU/ ArpcfBK1ry8jUJ6JElnsIaik/sKUHYHyfSAQ/CLrSqf4TmLhO0mpT/zOxut0rvU75VVG hrqe9ZaFXXaCFMfgTABHYK+2cnHCGMSrIMNxrOxuRvVG6d0rfoz51EZHiJ+HlLhLmNi4 pU7CSl/q+4WrCgwi/To12MOW64/oiioBJNuzs15IpgqDSSeeJbUf40aXCGcjPMSqnVRx gwurXxKS/7Wfns9N7jxco9HoHn+5H4uf4pQBIPm815TYhTeHOWtDUW5AILSPBTQkrtF3 DXew== X-Gm-Message-State: AJIora/TOgnJlwIjAg6I4GAvBqy9Bgwso3DXXAFbMOPeKrFrlOMUDrjL EGxe/iOOnhDbHykyJfwryL0FX1ECi0RV/g== X-Google-Smtp-Source: AGRyM1tUQB2lXjJBnAglK9mwr2T2JMV9YrW94IBl8OIgH3FRs6gXBpL6/tD0EaErzA4pjicf2/cmMA== X-Received: by 2002:a5d:65c3:0:b0:21b:bca9:83b1 with SMTP id e3-20020a5d65c3000000b0021bbca983b1mr18818447wrw.568.1656446579293; Tue, 28 Jun 2022 13:02:59 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id p2-20020a05600c358200b003942a244f47sm642902wmq.32.2022.06.28.13.02.58 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 28 Jun 2022 13:02:58 -0700 (PDT) Message-Id: In-Reply-To: References: From: "Derrick Stolee via GitGitGadget" Date: Tue, 28 Jun 2022 20:02:57 +0000 Subject: [PATCH v2] git-rebase.txt: use back-ticks consistently Fcc: Sent Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit MIME-Version: 1.0 To: git@vger.kernel.org Cc: gitster@pobox.com, me@ttaylorr.com, Johannes.Schindelin@gmx.de, Phillip Wood , =?UTF-8?Q?=C3=86var_Arnfj=C3=B6r=C3=B0?= Bjarmason , Derrick Stolee , Derrick Stolee Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Derrick Stolee While inspecting the 'git rebase' documentation, I noticed that it is inconsistent with how it uses back-ticks (or other punctuation) for identifying Git commands, command-line arguments, or values for those arguments. Sometimes, an argument (like '--interactive') would appear without any punctuation, causing the argument to not have any special formatting. Other times, arguments or 'git rebase' itself would have single-quotes giving a bold look (in the HTML documentation at least). By consistently using back-ticks, these types of strings appear in a monospace font with special highlighting to appear more clearly as text that exists in a command-line invocation of a Git command. This rather-large diff is the result of scanning git-rebase.txt and adding back-ticks as appropriate. Some are adding back-ticks where there was no punctuation. Others are replacing single quotes. There are also a few minor cleanups in the process, including those found by reviwers. Helped-by: Phillip Wood Helped-by: Junio C Hamano Signed-off-by: Derrick Stolee --- git-rebase.txt: use back-ticks consistently While I noticed this inconsistency when looking at git rebase as part of the git rebase --update-refs work, I didn't know the best way to update the document from start to finish. Feedback tells me that splitting this patch isn't worth it. Updates in v2 ============= * The 'apply' and 'merge' backends are now quoted with single quotes instead of back-ticks. (Phrases such as "the merge command" describing the todo file still use back-ticks.) * The pre-rebase hook now has back-ticks. * An unnecessary comma is removed. * When talking about 'ours' and 'theirs' as "sides" of a rebase, use single quotes. Use back-ticks only for the ours strategy. * A bulleted list is converted to use ";;" syntax. Thanks, -Stolee Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1270%2Fderrickstolee%2Frebase-docs-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1270/derrickstolee/rebase-docs-v2 Pull-Request: https://github.com/gitgitgadget/git/pull/1270 Range-diff vs v1: 1: 71520dc1b71 ! 1: 02983cdb79d git-rebase.txt: use back-ticks consistently @@ Commit message adding back-ticks as appropriate. Some are adding back-ticks where there was no punctuation. Others are replacing single quotes. - There are also a few minor cleanups in the process, such as one place - that did not use tabs for the first paragraph in a bulletted list. - Another case still referred to the dashed form, but it was the only use - in the file except for the heading and NAME section. + There are also a few minor cleanups in the process, including those + found by reviwers. + Helped-by: Phillip Wood + Helped-by: Junio C Hamano Signed-off-by: Derrick Stolee ## Documentation/git-rebase.txt ## @@ Documentation/git-rebase.txt: SYNOPSIS -The current branch is reset to , or if the ---onto option was supplied. This has the exact same effect as -`git reset --hard ` (or ). ORIG_HEAD is set -+The current branch is reset to ``, or `` if the ++The current branch is reset to `` or `` if the +`--onto` option was supplied. This has the exact same effect as +`git reset --hard ` (or ``). `ORIG_HEAD` is set to point at the tip of the branch before the reset. @@ Documentation/git-rebase.txt: SYNOPSIS Assume the following history exists and the current branch is "topic": +@@ Documentation/git-rebase.txt: remain the checked-out branch. + + If the upstream branch already contains a change you have made (e.g., + because you mailed a patch which was applied upstream), then that commit +-will be skipped and warnings will be issued (if the `merge` backend is ++will be skipped and warnings will be issued (if the 'merge' backend is + used). For example, running `git rebase master` on the following + history (in which `A'` and `A` introduce the same set of changes, but + have different committer information): @@ Documentation/git-rebase.txt: would result in the removal of commits F and G: ------------ @@ Documentation/git-rebase.txt: flag exists as a convenient shortcut, such as for + See also INCOMPATIBLE OPTIONS below. +@@ Documentation/git-rebase.txt: See also INCOMPATIBLE OPTIONS below. + By default (or if `--no-reapply-cherry-picks` is given), these commits + will be automatically dropped. Because this necessitates reading all + upstream commits, this can be expensive in repos with a large number +-of upstream commits that need to be read. When using the `merge` ++of upstream commits that need to be read. When using the 'merge' + backend, warnings will be issued for each dropped commit (unless + `--quiet` is given). Advice will also be issued unless + `advice.skippedCherryPicks` is set to false (see linkgit:git-config[1]). @@ Documentation/git-rebase.txt: See also INCOMPATIBLE OPTIONS below. Using merging strategies to rebase (default). + @@ Documentation/git-rebase.txt: See also INCOMPATIBLE OPTIONS below. which makes little sense. + See also INCOMPATIBLE OPTIONS below. -@@ Documentation/git-rebase.txt: See also INCOMPATIBLE OPTIONS below. - --strategy-option=:: - Pass the through to the merge strategy. - This implies `--merge` and, if no strategy has been -- specified, `-s ort`. Note the reversal of 'ours' and -- 'theirs' as noted above for the `-m` option. -+ specified, `-s ort`. Note the reversal of `ours` and -+ `theirs` as noted above for the `-m` option. - + - See also INCOMPATIBLE OPTIONS below. - @@ Documentation/git-rebase.txt: See also INCOMPATIBLE OPTIONS below. -q:: @@ Documentation/git-rebase.txt: See also INCOMPATIBLE OPTIONS below. + this behavior: + -apply backend: When applying a patch, ignore changes in whitespace in -+'apply backend:' When applying a patch, ignore changes in whitespace in - context lines. Unfortunately, this means that if the "old" lines being - replaced by the patch differ only in whitespace from the existing - file, you will get a merge conflict instead of a successful patch - application. +-context lines. Unfortunately, this means that if the "old" lines being +-replaced by the patch differ only in whitespace from the existing +-file, you will get a merge conflict instead of a successful patch +-application. ++apply backend:;; ++ When applying a patch, ignore changes in whitespace in context ++ lines. Unfortunately, this means that if the "old" lines being ++ replaced by the patch differ only in whitespace from the existing ++ file, you will get a merge conflict instead of a successful patch ++ application. + -merge backend: Treat lines with only whitespace changes as unchanged -+'merge backend:' Treat lines with only whitespace changes as unchanged - when merging. Unfortunately, this means that any patch hunks that were - intended to modify whitespace and nothing else will be dropped, even - if the other side had no changes that conflicted. +-when merging. Unfortunately, this means that any patch hunks that were +-intended to modify whitespace and nothing else will be dropped, even +-if the other side had no changes that conflicted. ++merge backend:;; ++ Treat lines with only whitespace changes as unchanged when merging. ++ Unfortunately, this means that any patch hunks that were intended ++ to modify whitespace and nothing else will be dropped, even if the ++ other side had no changes that conflicted. --whitespace=