On Mon, Aug 03, 2020 at 08:55:30PM -0400, Eric Sunshine wrote: > This is a re-roll of [1] which fixes some problems I ran across in the > git-worktree documentation while working on another worktree-related > topic. > > This version adds some `linkgit:` invocations, typesets `HEAD` as > fixed-width, and covers a few additional places where backticks should > have been applied in place of other quotes, as suggested by Martin[2], > as well as a few more I noticed beyond those found by him. Although I > had planned on adding backticks around `HEAD` in a separate patch, I > ended up folding that change into patch 1 since there are relatively few > such instances, and since, upon reflection, such a change didn't seem to > warrant its own patch. > > I omitted Taylor's Reviewed-by:[4] since the patches have changed since > he reviewed them, but he's welcome to give it again. Thanks for dropping that. I looked at the inter-diff and skimmed the re-rolled patches, and they all look good to me. You can add my Reviewed-by: Taylor Blau <me@xxxxxxxxxxxx> back to these patches (really Junio can when he queues them). Thanks. > > [1]: https://lore.kernel.org/git/20200803053612.50095-1-sunshine@xxxxxxxxxxxxxx/ > [2]: https://lore.kernel.org/git/20200803175717.7465-1-martin.agren@xxxxxxxxx/ > [3]: https://lore.kernel.org/git/CAPig+cQtcxqQDAQ5bO6ica+Z7dd2+r8B+kXm0RK7qhpsAiX_xg@xxxxxxxxxxxxxx/ > [4]: https://lore.kernel.org/git/20200803161102.GB50799@xxxxxxx/ > > Eric Sunshine (5): > git-worktree.txt: employ fixed-width typeface consistently > git-worktree.txt: consistently use term "working tree" > git-worktree.txt: fix minor grammatical issues > git-worktree.txt: make start of new sentence more obvious > git-wortkree.txt: link to man pages when citing other Git commands > > Documentation/git-worktree.txt | 123 +++++++++++++++++---------------- > 1 file changed, 62 insertions(+), 61 deletions(-) > > Interdiff against v1: > diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt > index 260bfe9105..6ee6ec7982 100644 > --- a/Documentation/git-worktree.txt > +++ b/Documentation/git-worktree.txt > @@ -25,8 +25,9 @@ Manage multiple working trees attached to the same repository. > A git repository can support multiple working trees, allowing you to check > out more than one branch at a time. With `git worktree add` a new working > tree is associated with the repository. This new working tree is called a > -"linked working tree" as opposed to the "main working tree" prepared by "git > -init" or "git clone". A repository has one main working tree (if it's not a > +"linked working tree" as opposed to the "main working tree" prepared by > +linkgit:git-init[1] or linkgit:git-clone[1]. > +A repository has one main working tree (if it's not a > bare repository) and zero or more linked working trees. When you are done > with a linked working tree, remove it with `git worktree remove`. > > @@ -48,7 +49,7 @@ add <path> [<commit-ish>]:: > > Create `<path>` and checkout `<commit-ish>` into it. The new working directory > is linked to the current repository, sharing everything except working > -directory specific files such as HEAD, index, etc. As a convenience, > +directory specific files such as `HEAD`, `index`, etc. As a convenience, > `<commit-ish>` may be a bare "`-`", which is synonymous with `@{-1}`. > + > If `<commit-ish>` is a branch name (call it `<branch>`) and is not found, > @@ -66,13 +67,13 @@ one for the purposes of disambiguation, even if the `<branch>` isn't > unique across all remotes. Set it to > e.g. `checkout.defaultRemote=origin` to always checkout remote > branches from there if `<branch>` is ambiguous but exists on the > -'origin' remote. See also `checkout.defaultRemote` in > +`origin` remote. See also `checkout.defaultRemote` in > linkgit:git-config[1]. > + > If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used, > then, as a convenience, the new working tree is associated with a branch > (call it `<branch>`) named after `$(basename <path>)`. If `<branch>` > -doesn't exist, a new branch based on HEAD is automatically created as > +doesn't exist, a new branch based on `HEAD` is automatically created as > if `-b <branch>` was given. If `<branch>` does exist, it will be > checked out in the new working tree, if it's not checked out anywhere > else, otherwise the command will refuse to create the working tree (unless > @@ -137,13 +138,13 @@ To remove a locked working tree, specify `--force` twice. > -B <new-branch>:: > With `add`, create a new branch named `<new-branch>` starting at > `<commit-ish>`, and check out `<new-branch>` into the new working tree. > - If `<commit-ish>` is omitted, it defaults to HEAD. > + If `<commit-ish>` is omitted, it defaults to `HEAD`. > By default, `-b` refuses to create a new branch if it already > exists. `-B` overrides this safeguard, resetting `<new-branch>` to > `<commit-ish>`. > > --detach:: > - With `add`, detach HEAD in the new working tree. See "DETACHED HEAD" > + With `add`, detach `HEAD` in the new working tree. See "DETACHED HEAD" > in linkgit:git-checkout[1]. > > --[no-]checkout:: > @@ -154,7 +155,7 @@ To remove a locked working tree, specify `--force` twice. > > --[no-]guess-remote:: > With `worktree add <path>`, without `<commit-ish>`, instead > - of creating a new branch from HEAD, if there exists a tracking > + of creating a new branch from `HEAD`, if there exists a tracking > branch in exactly one remote matching the basename of `<path>`, > base the new branch on the remote-tracking branch, and mark > the remote-tracking branch as "upstream" from the new branch. > @@ -166,7 +167,7 @@ This can also be set up as the default behaviour by using the > When creating a new branch, if `<commit-ish>` is a branch, > mark it as "upstream" from the new branch. This is the > default if `<commit-ish>` is a remote-tracking branch. See > - "--track" in linkgit:git-branch[1] for details. > + `--track` in linkgit:git-branch[1] for details. > > --lock:: > Keep the working tree locked after creation. This is the > @@ -185,14 +186,14 @@ This can also be set up as the default behaviour by using the > > -q:: > --quiet:: > - With 'add', suppress feedback messages. > + With `add`, suppress feedback messages. > > -v:: > --verbose:: > With `prune`, report all removals. > > --expire <time>:: > - With `prune`, only expire unused working trees older than <time>. > + With `prune`, only expire unused working trees older than `<time>`. > > --reason <string>:: > With `lock`, an explanation why the working tree is locked. > @@ -209,12 +210,12 @@ then `ghi` or `def/ghi` is enough to point to the former working tree. > REFS > ---- > In multiple working trees, some refs may be shared between all working > -trees and some refs are local. One example is HEAD which is different for each > +trees and some refs are local. One example is `HEAD` which is different for each > working tree. This section is about the sharing rules and how to access > refs of one working tree from another. > > In general, all pseudo refs are per working tree and all refs starting > -with `refs/` are shared. Pseudo refs are ones like HEAD which are > +with `refs/` are shared. Pseudo refs are ones like `HEAD` which are > directly under `$GIT_DIR` instead of inside `$GIT_DIR/refs`. There are > exceptions, however: refs inside `refs/bisect` and `refs/worktree` are not > shared. > @@ -225,7 +226,7 @@ former gives access to per-working tree refs of the main working tree, > while the latter to all linked working trees. > > For example, `main-worktree/HEAD` or `main-worktree/refs/bisect/good` > -resolve to the same value as the main working tree's HEAD and > +resolve to the same value as the main working tree's `HEAD` and > `refs/bisect/good` respectively. Similarly, `worktrees/foo/HEAD` or > `worktrees/bar/refs/bisect/bad` are the same as > `$GIT_COMMON_DIR/worktrees/foo/HEAD` and > @@ -237,13 +238,13 @@ which will handle refs correctly. > > CONFIGURATION FILE > ------------------ > -By default, the repository "config" file is shared across all working > +By default, the repository `config` file is shared across all working > trees. If the config variables `core.bare` or `core.worktree` are > already present in the config file, they will be applied to the main > working trees only. > > In order to have configuration specific to working trees, you can turn > -on "worktreeConfig" extension, e.g.: > +on the `worktreeConfig` extension, e.g.: > > ------------ > $ git config extensions.worktreeConfig true > -- > 2.28.0.236.gb10cc79966 > Thanks, Taylor
