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,RCVD_IN_DNSWL_HI, SPF_HELO_NONE,SPF_PASS,T_SCC_BODY_TEXT_LINE,URIBL_CSS,URIBL_CSS_A 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 7E3ED1F727 for ; Wed, 29 Jun 2022 13:21:34 +0000 (UTC) Authentication-Results: dcvr.yhbt.net; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="Et9ZRG7B"; dkim-atps=neutral Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233322AbiF2NVQ (ORCPT ); Wed, 29 Jun 2022 09:21:16 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54074 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232700AbiF2NVP (ORCPT ); Wed, 29 Jun 2022 09:21:15 -0400 Received: from mail-wr1-x429.google.com (mail-wr1-x429.google.com [IPv6:2a00:1450:4864:20::429]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D7B1434652 for ; Wed, 29 Jun 2022 06:21:12 -0700 (PDT) Received: by mail-wr1-x429.google.com with SMTP id v14so22439176wra.5 for ; Wed, 29 Jun 2022 06:21:12 -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=Gmi0cVvVcRSD+n/uECg7q7I8UoIz50wSUd9WoDJFPlc=; b=Et9ZRG7BTCVqJeMqCms/jJw46+9NGlzxs4KSazwnpdMrJY827I7sKwZMflsq1a92bq bF5MjWaxfBmXDTCU/svUrzSscNP2ga34oViMTKNH4ZmJfaLnWepGqsERufRRlY/Ee9Uo sRXpXe24Fn0mbmSjXwH209mg2iAEefd9qPAVrnzQtskP2SYT2p3/4Tyd4sJg+dGOa1f4 9cF8eP/hguwHS4iBteLWnOYdkiNdTOR4dKMO6Y6XVmMzuFXk4T/+KKeOHFcP6aofn6n1 xZvLZp6enwkk9ZHGnxdZHjxysfDVMWjS0B57+Wpf9X5fpXz4XIAj3AsAaEMfGp4OlC8W uVbQ== 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=Gmi0cVvVcRSD+n/uECg7q7I8UoIz50wSUd9WoDJFPlc=; b=DFEdKqllEua0N8sP8L7MKzqMQcb217xY1xNnapx0oZgr8UGx+i+mCcd3k83YXX+aRc JkpdNvi2gjlzwPzQxg4wB5HOqow5uY9otDSI5D35N/6wSkxXq5yhVhrOF8lVyHJTYlEQ B7Lhk/86afPnpJLOxYWLiFY43j/c8VYuzuPkI7xO5UuwJJeOVZFOXQVisl6KYDV+a2JG PcKPHyv2iSeferShQF4GjssQ0xQL7jmX1ISh4rmRqmwrCvmapYHi2eW7Oiuosh05ilVh +6hQUNAsOKQcCC6VmfzbZ+Jn7P2kJ+sSuV5Ud9XGpz0rZ90W8M23JxZdrdZX/PewHOeK 9o9Q== X-Gm-Message-State: AJIora8JTOE4vpZktkag6XvyNq+1z9hvYGuN9jqohfVw8XLM9C1LIXkC grvXS0LzH6nm4XRKwWVgiYjC3aNi+5Uskg== X-Google-Smtp-Source: AGRyM1vcUhqo1hbHEBDwyUvPVI03bwknxHR0ea2/Cp/iqISlpJyODTOTxnYajZvgQStVAMxnZIMY3Q== X-Received: by 2002:adf:ec4f:0:b0:21b:90c0:139e with SMTP id w15-20020adfec4f000000b0021b90c0139emr3108763wrn.550.1656508869997; Wed, 29 Jun 2022 06:21:09 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id m12-20020a05600c3b0c00b00397402ae674sm3274592wms.11.2022.06.29.06.21.08 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 29 Jun 2022 06:21:09 -0700 (PDT) Message-Id: In-Reply-To: References: From: "Derrick Stolee via GitGitGadget" Date: Wed, 29 Jun 2022 13:21:07 +0000 Subject: [PATCH v3] 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 reviewers. 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 v3 ============= * A much smaller round of edits, but huge thanks to Junio and Phillip for a careful attention to detail. * Use 'am' over am. * Don't use colons in subsection headings. * Fix a commit message typo. 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-v3 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1270/derrickstolee/rebase-docs-v3 Pull-Request: https://github.com/gitgitgadget/git/pull/1270 Range-diff vs v2: 1: 02983cdb79d ! 1: 9c59d120c14 git-rebase.txt: use back-ticks consistently @@ Commit message was no punctuation. Others are replacing single quotes. There are also a few minor cleanups in the process, including those - found by reviwers. + found by reviewers. Helped-by: Phillip Wood Helped-by: Junio C Hamano @@ Documentation/git-rebase.txt: See also INCOMPATIBLE OPTIONS below. -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:;; ++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 @@ Documentation/git-rebase.txt: See also INCOMPATIBLE OPTIONS below. -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:;; ++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 @@ Documentation/git-rebase.txt: In addition, the following pairs of options are in ----------------------- -git rebase has two primary backends: apply and merge. (The apply --backend used to be known as the 'am' backend, but the name led to --confusion as it looks like a verb instead of a noun. Also, the merge +`git rebase` has two primary backends: 'apply' and 'merge'. (The 'apply' -+backend used to be known as the `am` backend, but the name led to + backend used to be known as the 'am' backend, but the name led to +-confusion as it looks like a verb instead of a noun. Also, the merge +confusion as it looks like a verb instead of a noun. Also, the 'merge' backend used to be known as the interactive backend, but it is now used for non-interactive cases as well. Both were renamed based on Documentation/git-rebase.txt | 242 ++++++++++++++++++----------------- 1 file changed, 122 insertions(+), 120 deletions(-) diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 262fb01aec0..a872ab0fbd1 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -16,40 +16,40 @@ SYNOPSIS DESCRIPTION ----------- -If is specified, 'git rebase' will perform an automatic +If `` is specified, `git rebase` will perform an automatic `git switch ` before doing anything else. Otherwise it remains on the current branch. -If is not specified, the upstream configured in -branch..remote and branch..merge options will be used (see +If `` is not specified, the upstream configured in +`branch..remote` and `branch..merge` options will be used (see linkgit:git-config[1] for details) and the `--fork-point` option is assumed. If you are currently not on any branch or if the current branch does not have a configured upstream, the rebase will abort. All changes made by commits in the current branch but that are not -in are saved to a temporary area. This is the same set +in `` are saved to a temporary area. This is the same set of commits that would be shown by `git log ..HEAD`; or by `git log 'fork_point'..HEAD`, if `--fork-point` is active (see the description on `--fork-point` below); or by `git log HEAD`, if the `--root` option is specified. -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 +`--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. The commits that were previously saved into the temporary area are then reapplied to the current branch, one by one, in order. Note that -any commits in HEAD which introduce the same textual changes as a commit -in HEAD.. are omitted (i.e., a patch already accepted upstream +any commits in `HEAD` which introduce the same textual changes as a commit +in `HEAD..` are omitted (i.e., a patch already accepted upstream with a different commit message or timestamp will be skipped). It is possible that a merge failure will prevent this process from being completely automatic. You will have to resolve any such merge failure and run `git rebase --continue`. Another option is to bypass the commit that caused the merge failure with `git rebase --skip`. To check out the -original and remove the .git/rebase-apply working files, use the -command `git rebase --abort` instead. +original `` and remove the `.git/rebase-apply` working files, use +the command `git rebase --abort` instead. Assume the following history exists and the current branch is "topic": @@ -79,7 +79,7 @@ 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): @@ -176,11 +176,11 @@ would result in the removal of commits F and G: ------------ This is useful if F and G were flawed in some way, or should not be -part of topicA. Note that the argument to --onto and the +part of topicA. Note that the argument to `--onto` and the `` parameter can be any valid commit-ish. -In case of conflict, 'git rebase' will stop at the first problematic commit -and leave conflict markers in the tree. You can use 'git diff' to locate +In case of conflict, `git rebase` will stop at the first problematic commit +and leave conflict markers in the tree. You can use `git diff` to locate the markers (<<<<<<) and make edits to resolve the conflict. For each file you edit, you need to tell Git that the conflict has been resolved, typically this would be done with @@ -205,8 +205,8 @@ OPTIONS ------- --onto :: Starting point at which to create the new commits. If the - --onto option is not specified, the starting point is - . May be any valid commit, and not just an + `--onto` option is not specified, the starting point is + ``. May be any valid commit, and not just an existing branch name. + As a special case, you may use "A\...B" as a shortcut for the @@ -215,19 +215,19 @@ leave out at most one of A and B, in which case it defaults to HEAD. --keep-base:: Set the starting point at which to create the new commits to the - merge base of and . Running - 'git rebase --keep-base ' is equivalent to + merge base of `` and ``. Running + `git rebase --keep-base ` is equivalent to running - 'git rebase --onto ... '. + `git rebase --onto ... `. + This option is useful in the case where one is developing a feature on top of an upstream branch. While the feature is being worked on, the upstream branch may advance and it may not be the best idea to keep rebasing on top of the upstream but to keep the base commit as-is. + -Although both this option and --fork-point find the merge base between - and , this option uses the merge base as the _starting -point_ on which new commits will be created, whereas --fork-point uses +Although both this option and `--fork-point` find the merge base between +`` and ``, this option uses the merge base as the _starting +point_ on which new commits will be created, whereas `--fork-point` uses the merge base to determine the _set of commits_ which will be rebased. + See also INCOMPATIBLE OPTIONS below. @@ -238,23 +238,23 @@ See also INCOMPATIBLE OPTIONS below. upstream for the current branch. :: - Working branch; defaults to HEAD. + Working branch; defaults to `HEAD`. --continue:: Restart the rebasing process after having resolved a merge conflict. --abort:: Abort the rebase operation and reset HEAD to the original - branch. If was provided when the rebase operation was - started, then HEAD will be reset to . Otherwise HEAD + branch. If `` was provided when the rebase operation was + started, then `HEAD` will be reset to ``. Otherwise `HEAD` will be reset to where it was when the rebase operation was started. --quit:: - Abort the rebase operation but HEAD is not reset back to the + Abort the rebase operation but `HEAD` is not reset back to the original branch. The index and working tree are also left unchanged as a result. If a temporary stash entry was created - using --autostash, it will be saved to the stash list. + using `--autostash`, it will be saved to the stash list. --apply:: Use applying strategies to rebase (calling `git-am` @@ -269,16 +269,16 @@ See also INCOMPATIBLE OPTIONS below. empty after rebasing (because they contain a subset of already upstream changes). With drop (the default), commits that become empty are dropped. With keep, such commits are kept. - With ask (implied by --interactive), the rebase will halt when + With ask (implied by `--interactive`), the rebase will halt when an empty commit is applied allowing you to choose whether to drop it, edit files more, or just commit the empty changes. - Other options, like --exec, will use the default of drop unless - -i/--interactive is explicitly specified. + Other options, like `--exec`, will use the default of drop unless + `-i`/`--interactive` is explicitly specified. + -Note that commits which start empty are kept (unless --no-keep-empty +Note that commits which start empty are kept (unless `--no-keep-empty` is specified), and commits which are clean cherry-picks (as determined by `git log --cherry-mark ...`) are detected and dropped as a -preliminary step (unless --reapply-cherry-picks is passed). +preliminary step (unless `--reapply-cherry-picks` is passed). + See also INCOMPATIBLE OPTIONS below. @@ -287,7 +287,7 @@ See also INCOMPATIBLE OPTIONS below. Do not keep commits that start empty before the rebase (i.e. that do not change anything from its parent) in the result. The default is to keep commits which start empty, - since creating such commits requires passing the --allow-empty + since creating such commits requires passing the `--allow-empty` override flag to `git commit`, signifying that a user is very intentionally creating such a commit and thus wants to keep it. @@ -299,7 +299,7 @@ flag exists as a convenient shortcut, such as for cases where external tools generate many empty commits and you want them all removed. + For commits which do not start empty but become empty after rebasing, -see the --empty flag. +see the `--empty` flag. + See also INCOMPATIBLE OPTIONS below. @@ -314,7 +314,7 @@ 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]). @@ -348,10 +348,10 @@ See also INCOMPATIBLE OPTIONS below. Using merging strategies to rebase (default). + Note that a rebase merge works by replaying each commit from the working -branch on top of the branch. Because of this, when a merge +branch on top of the `` branch. Because of this, when a merge conflict happens, the side reported as 'ours' is the so-far rebased -series, starting with , and 'theirs' is the working branch. In -other words, the sides are swapped. +series, starting with ``, and 'theirs' is the working branch. +In other words, the sides are swapped. + See also INCOMPATIBLE OPTIONS below. @@ -360,9 +360,9 @@ See also INCOMPATIBLE OPTIONS below. Use the given merge strategy, instead of the default `ort`. This implies `--merge`. + -Because 'git rebase' replays each commit from the working branch -on top of the branch using the given strategy, using -the 'ours' strategy simply empties all patches from the , +Because `git rebase` replays each commit from the working branch +on top of the `` branch using the given strategy, using +the `ours` strategy simply empties all patches from the ``, which makes little sense. + See also INCOMPATIBLE OPTIONS below. @@ -392,11 +392,11 @@ See also INCOMPATIBLE OPTIONS below. -q:: --quiet:: - Be quiet. Implies --no-stat. + Be quiet. Implies `--no-stat`. -v:: --verbose:: - Be verbose. Implies --stat. + Be verbose. Implies `--stat`. --stat:: Show a diffstat of what changed upstream since the last rebase. The @@ -411,13 +411,13 @@ See also INCOMPATIBLE OPTIONS below. --verify:: Allows the pre-rebase hook to run, which is the default. This option can - be used to override --no-verify. See also linkgit:githooks[5]. + be used to override `--no-verify`. See also linkgit:githooks[5]. -C:: - Ensure at least lines of surrounding context match before + Ensure at least `` lines of surrounding context match before and after each change. When fewer lines of surrounding context exist they all must match. By default no context is - ever ignored. Implies --apply. + ever ignored. Implies `--apply`. + See also INCOMPATIBLE OPTIONS below. @@ -436,21 +436,21 @@ details). --fork-point:: --no-fork-point:: - Use reflog to find a better common ancestor between - and when calculating which commits have been - introduced by . + Use reflog to find a better common ancestor between `` + and `` when calculating which commits have been + introduced by ``. + -When --fork-point is active, 'fork_point' will be used instead of - to calculate the set of commits to rebase, where +When `--fork-point` is active, 'fork_point' will be used instead of +`` to calculate the set of commits to rebase, where 'fork_point' is the result of `git merge-base --fork-point ` command (see linkgit:git-merge-base[1]). If 'fork_point' -ends up being empty, the will be used as a fallback. +ends up being empty, the `` will be used as a fallback. + -If is given on the command line, then the default is +If `` is given on the command line, then the default is `--no-fork-point`, otherwise the default is `--fork-point`. See also `rebase.forkpoint` in linkgit:git-config[1]. + -If your branch was based on but was rewound and +If your branch was based on `` but `` was rewound and your branch contains commits which were dropped, this option can be used with `--keep-base` in order to drop those commits from your branch. + @@ -458,24 +458,26 @@ See also INCOMPATIBLE OPTIONS below. --ignore-whitespace:: Ignore whitespace differences when trying to reconcile -differences. Currently, each backend implements an approximation of -this behavior: + differences. Currently, each backend implements an approximation of + this behavior: + -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. +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 -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=