freshlybakedca.ke / git
Git fork
fork atom

doc: convert git worktree to synopsis style

- Switch the synopsis to a synopsis block which will automatically
format placeholders in italics and keywords in monospace
- Use _<placeholder>_ instead of <placeholder> in the description
- Use `backticks` for keywords and more complex option
descriptions. The new rendering engine will apply synopsis rules to
these spans.

Also add the config section in the manual page and do not refer to the man
page in the description of settings when this description is already in the
man page.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

authored by

Jean-Noël Avila and committed by
Junio C Hamano 0ae23ab5 0fc3a21a

+91 -84
unified split
+7 -7
Documentation/config/worktree.adoc
··· 1 - worktree.guessRemote:: 1 + `worktree.guessRemote`:: 2 2 If no branch is specified and neither `-b` nor `-B` nor 3 3 `--detach` is used, then `git worktree add` defaults to 4 4 creating a new branch from HEAD. If `worktree.guessRemote` is ··· 6 6 branch whose name uniquely matches the new branch name. If 7 7 such a branch exists, it is checked out and set as "upstream" 8 8 for the new branch. If no such match can be found, it falls 9 - back to creating a new branch from the current HEAD. 9 + back to creating a new branch from the current `HEAD`. 10 10 11 - worktree.useRelativePaths:: 12 - Link worktrees using relative paths (when "true") or absolute 13 - paths (when "false"). This is particularly useful for setups 11 + `worktree.useRelativePaths`:: 12 + Link worktrees using relative paths (when "`true`") or absolute 13 + paths (when "`false`"). This is particularly useful for setups 14 14 where the repository and worktrees may be moved between 15 - different locations or environments. Defaults to "false". 15 + different locations or environments. Defaults to "`false`". 16 16 + 17 - Note that setting `worktree.useRelativePaths` to "true" implies enabling the 17 + Note that setting `worktree.useRelativePaths` to "`true`" implies enabling the 18 18 `extensions.relativeWorktrees` config (see linkgit:git-config[1]), 19 19 thus making it incompatible with older versions of Git.
+84 -77
Documentation/git-worktree.adoc
··· 8 8 9 9 SYNOPSIS 10 10 -------- 11 - [verse] 12 - 'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] 13 - [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>] 14 - 'git worktree list' [-v | --porcelain [-z]] 15 - 'git worktree lock' [--reason <string>] <worktree> 16 - 'git worktree move' <worktree> <new-path> 17 - 'git worktree prune' [-n] [-v] [--expire <expire>] 18 - 'git worktree remove' [-f] <worktree> 19 - 'git worktree repair' [<path>...] 20 - 'git worktree unlock' <worktree> 11 + [synopsis] 12 + git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]] 13 + [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>] 14 + git worktree list [-v | --porcelain [-z]] 15 + git worktree lock [--reason <string>] <worktree> 16 + git worktree move <worktree> <new-path> 17 + git worktree prune [-n] [-v] [--expire <expire>] 18 + git worktree remove [-f] <worktree> 19 + git worktree repair [<path>...] 20 + git worktree unlock <worktree> 21 21 22 22 DESCRIPTION 23 23 ----------- ··· 37 37 remove it with `git worktree remove`. 38 38 39 39 In its simplest form, `git worktree add <path>` automatically creates a 40 - new branch whose name is the final component of `<path>`, which is 40 + new branch whose name is the final component of _<path>_, which is 41 41 convenient if you plan to work on a new topic. For instance, `git 42 42 worktree add ../hotfix` creates new branch `hotfix` and checks it out at 43 43 path `../hotfix`. To instead work on an existing branch in a new worktree, ··· 63 63 64 64 COMMANDS 65 65 -------- 66 - add <path> [<commit-ish>]:: 66 + `add <path> [<commit-ish>]`:: 67 67 68 - Create a worktree at `<path>` and checkout `<commit-ish>` into it. The new worktree 68 + Create a worktree at _<path>_ and checkout _<commit-ish>_ into it. The new worktree 69 69 is linked to the current repository, sharing everything except per-worktree 70 - files such as `HEAD`, `index`, etc. As a convenience, `<commit-ish>` may 70 + files such as `HEAD`, `index`, etc. As a convenience, _<commit-ish>_ may 71 71 be a bare "`-`", which is synonymous with `@{-1}`. 72 72 + 73 - If `<commit-ish>` is a branch name (call it `<branch>`) and is not found, 73 + If _<commit-ish>_ is a branch name (call it _<branch>_) and is not found, 74 74 and neither `-b` nor `-B` nor `--detach` are used, but there does 75 - exist a tracking branch in exactly one remote (call it `<remote>`) 75 + exist a tracking branch in exactly one remote (call it _<remote>_) 76 76 with a matching name, treat as equivalent to: 77 77 + 78 78 ------------ ··· 81 81 + 82 82 If the branch exists in multiple remotes and one of them is named by 83 83 the `checkout.defaultRemote` configuration variable, we'll use that 84 - one for the purposes of disambiguation, even if the `<branch>` isn't 84 + one for the purposes of disambiguation, even if the _<branch>_ isn't 85 85 unique across all remotes. Set it to 86 86 e.g. `checkout.defaultRemote=origin` to always checkout remote 87 - branches from there if `<branch>` is ambiguous but exists on the 87 + branches from there if _<branch>_ is ambiguous but exists on the 88 88 `origin` remote. See also `checkout.defaultRemote` in 89 89 linkgit:git-config[1]. 90 90 + 91 - If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used, 91 + If _<commit-ish>_ is omitted and neither `-b` nor `-B` nor `--detach` used, 92 92 then, as a convenience, the new worktree is associated with a branch (call 93 - it `<branch>`) named after `$(basename <path>)`. If `<branch>` doesn't 93 + it _<branch>_) named after `$(basename <path>)`. If _<branch>_ doesn't 94 94 exist, a new branch based on `HEAD` is automatically created as if 95 - `-b <branch>` was given. If `<branch>` does exist, it will be checked out 95 + `-b <branch>` was given. If _<branch>_ does exist, it will be checked out 96 96 in the new worktree, if it's not checked out anywhere else, otherwise the 97 97 command will refuse to create the worktree (unless `--force` is used). 98 98 + 99 - If `<commit-ish>` is omitted, neither `--detach`, or `--orphan` is 99 + If _<commit-ish>_ is omitted, neither `--detach`, or `--orphan` is 100 100 used, and there are no valid local branches (or remote branches if 101 101 `--guess-remote` is specified) then, as a convenience, the new worktree is 102 - associated with a new unborn branch named `<branch>` (after 102 + associated with a new unborn branch named _<branch>_ (after 103 103 `$(basename <path>)` if neither `-b` or `-B` is used) as if `--orphan` was 104 104 passed to the command. In the event the repository has a remote and 105 105 `--guess-remote` is used, but no remote or local branches exist, then the 106 106 command fails with a warning reminding the user to fetch from their remote 107 107 first (or override by using `-f/--force`). 108 108 109 - list:: 109 + `list`:: 110 110 111 111 List details of each worktree. The main worktree is listed first, 112 112 followed by each of the linked worktrees. The output details include ··· 115 115 the worktree is locked, "prunable" if the worktree can be pruned by the 116 116 `prune` command. 117 117 118 - lock:: 118 + `lock`:: 119 119 120 120 If a worktree is on a portable device or network share which is not always 121 121 mounted, lock it to prevent its administrative files from being pruned 122 122 automatically. This also prevents it from being moved or deleted. 123 123 Optionally, specify a reason for the lock with `--reason`. 124 124 125 - move:: 125 + `move`:: 126 126 127 127 Move a worktree to a new location. Note that the main worktree or linked 128 128 worktrees containing submodules cannot be moved with this command. (The 129 129 `git worktree repair` command, however, can reestablish the connection 130 130 with linked worktrees if you move the main worktree manually.) 131 131 132 - prune:: 132 + `prune`:: 133 133 134 134 Prune worktree information in `$GIT_DIR/worktrees`. 135 135 136 - remove:: 136 + `remove`:: 137 137 138 138 Remove a worktree. Only clean worktrees (no untracked files and no 139 139 modification in tracked files) can be removed. Unclean worktrees or ones 140 140 with submodules can be removed with `--force`. The main worktree cannot be 141 141 removed. 142 142 143 - repair [<path>...]:: 143 + `repair [<path>...]`:: 144 144 145 145 Repair worktree administrative files, if possible, if they have become 146 146 corrupted or outdated due to external factors. ··· 154 154 using `git worktree move`, the main worktree (or bare repository) will be 155 155 unable to locate it. Running `repair` within the recently-moved worktree 156 156 will reestablish the connection. If multiple linked worktrees are moved, 157 - running `repair` from any worktree with each tree's new `<path>` as an 157 + running `repair` from any worktree with each tree's new _<path>_ as an 158 158 argument, will reestablish the connection to all the specified paths. 159 159 + 160 160 If both the main worktree and linked worktrees have been moved or copied manually, 161 - then running `repair` in the main worktree and specifying the new `<path>` 161 + then running `repair` in the main worktree and specifying the new _<path>_ 162 162 of each linked worktree will reestablish all connections in both 163 163 directions. 164 164 165 - unlock:: 165 + `unlock`:: 166 166 167 167 Unlock a worktree, allowing it to be pruned, moved or deleted. 168 168 169 169 OPTIONS 170 170 ------- 171 171 172 - -f:: 173 - --force:: 172 + `-f`:: 173 + `--force`:: 174 174 By default, `add` refuses to create a new worktree when 175 - `<commit-ish>` is a branch name and is already checked out by 176 - another worktree, or if `<path>` is already assigned to some 177 - worktree but is missing (for instance, if `<path>` was deleted 175 + _<commit-ish>_ is a branch name and is already checked out by 176 + another worktree, or if _<path>_ is already assigned to some 177 + worktree but is missing (for instance, if _<path>_ was deleted 178 178 manually). This option overrides these safeguards. To add a missing but 179 179 locked worktree path, specify `--force` twice. 180 180 + 181 181 `move` refuses to move a locked worktree unless `--force` is specified 182 182 twice. If the destination is already assigned to some other worktree but is 183 - missing (for instance, if `<new-path>` was deleted manually), then `--force` 183 + missing (for instance, if _<new-path>_ was deleted manually), then `--force` 184 184 allows the move to proceed; use `--force` twice if the destination is locked. 185 185 + 186 186 `remove` refuses to remove an unclean worktree unless `--force` is used. 187 187 To remove a locked worktree, specify `--force` twice. 188 188 189 - -b <new-branch>:: 190 - -B <new-branch>:: 191 - With `add`, create a new branch named `<new-branch>` starting at 192 - `<commit-ish>`, and check out `<new-branch>` into the new worktree. 193 - If `<commit-ish>` is omitted, it defaults to `HEAD`. 189 + `-b <new-branch>`:: 190 + `-B <new-branch>`:: 191 + With `add`, create a new branch named _<new-branch>_ starting at 192 + _<commit-ish>_, and check out _<new-branch>_ into the new worktree. 193 + If _<commit-ish>_ is omitted, it defaults to `HEAD`. 194 194 By default, `-b` refuses to create a new branch if it already 195 - exists. `-B` overrides this safeguard, resetting `<new-branch>` to 196 - `<commit-ish>`. 195 + exists. `-B` overrides this safeguard, resetting _<new-branch>_ to 196 + _<commit-ish>_. 197 197 198 - -d:: 199 - --detach:: 198 + `-d`:: 199 + `--detach`:: 200 200 With `add`, detach `HEAD` in the new worktree. See "DETACHED HEAD" 201 201 in linkgit:git-checkout[1]. 202 202 203 - --checkout:: 204 - --no-checkout:: 205 - By default, `add` checks out `<commit-ish>`, however, `--no-checkout` can 203 + `--checkout`:: 204 + `--no-checkout`:: 205 + By default, `add` checks out _<commit-ish>_, however, `--no-checkout` can 206 206 be used to suppress checkout in order to make customizations, 207 207 such as configuring sparse-checkout. See "Sparse checkout" 208 208 in linkgit:git-read-tree[1]. 209 209 210 - --guess-remote:: 211 - --no-guess-remote:: 212 - With `worktree add <path>`, without `<commit-ish>`, instead 210 + `--guess-remote`:: 211 + `--no-guess-remote`:: 212 + With `worktree add <path>`, without _<commit-ish>_, instead 213 213 of creating a new branch from `HEAD`, if there exists a tracking 214 - branch in exactly one remote matching the basename of `<path>`, 214 + branch in exactly one remote matching the basename of _<path>_, 215 215 base the new branch on the remote-tracking branch, and mark 216 216 the remote-tracking branch as "upstream" from the new branch. 217 217 + 218 218 This can also be set up as the default behaviour by using the 219 219 `worktree.guessRemote` config option. 220 220 221 - --relative-paths:: 222 - --no-relative-paths:: 221 + `--relative-paths`:: 222 + `--no-relative-paths`:: 223 223 Link worktrees using relative paths or absolute paths (default). 224 224 Overrides the `worktree.useRelativePaths` config option, see 225 225 linkgit:git-config[1]. ··· 227 227 With `repair`, the linking files will be updated if there's an absolute/relative 228 228 mismatch, even if the links are correct. 229 229 230 - --track:: 231 - --no-track:: 232 - When creating a new branch, if `<commit-ish>` is a branch, 230 + `--track`:: 231 + `--no-track`:: 232 + When creating a new branch, if _<commit-ish>_ is a branch, 233 233 mark it as "upstream" from the new branch. This is the 234 - default if `<commit-ish>` is a remote-tracking branch. See 234 + default if _<commit-ish>_ is a remote-tracking branch. See 235 235 `--track` in linkgit:git-branch[1] for details. 236 236 237 - --lock:: 237 + `--lock`:: 238 238 Keep the worktree locked after creation. This is the 239 239 equivalent of `git worktree lock` after `git worktree add`, 240 240 but without a race condition. 241 241 242 - -n:: 243 - --dry-run:: 242 + `-n`:: 243 + `--dry-run`:: 244 244 With `prune`, do not remove anything; just report what it would 245 245 remove. 246 246 247 - --orphan:: 247 + `--orphan`:: 248 248 With `add`, make the new worktree and index empty, associating 249 - the worktree with a new unborn branch named `<new-branch>`. 249 + the worktree with a new unborn branch named _<new-branch>_. 250 250 251 - --porcelain:: 251 + `--porcelain`:: 252 252 With `list`, output in an easy-to-parse format for scripts. 253 253 This format will remain stable across Git versions and regardless of user 254 254 configuration. It is recommended to combine this with `-z`. 255 255 See below for details. 256 256 257 - -z:: 258 - Terminate each line with a NUL rather than a newline when 257 + `-z`:: 258 + Terminate each line with a _NUL_ rather than a newline when 259 259 `--porcelain` is specified with `list`. This makes it possible 260 260 to parse the output when a worktree path contains a newline 261 261 character. 262 262 263 - -q:: 264 - --quiet:: 263 + `-q`:: 264 + `--quiet`:: 265 265 With `add`, suppress feedback messages. 266 266 267 - -v:: 268 - --verbose:: 267 + `-v`:: 268 + `--verbose`:: 269 269 With `prune`, report all removals. 270 270 + 271 271 With `list`, output additional information about worktrees (see below). 272 272 273 - --expire <time>:: 274 - With `prune`, only expire unused worktrees older than `<time>`. 273 + `--expire <time>`:: 274 + With `prune`, only expire unused worktrees older than _<time>_. 275 275 + 276 276 With `list`, annotate missing worktrees as prunable if they are older than 277 - `<time>`. 277 + _<time>_. 278 278 279 - --reason <string>:: 279 + `--reason <string>`:: 280 280 With `lock` or with `add --lock`, an explanation why the worktree 281 281 is locked. 282 282 283 - <worktree>:: 283 + _<worktree>_:: 284 284 Worktrees can be identified by path, either relative or absolute. 285 285 + 286 286 If the last path components in the worktree's path is unique among ··· 521 521 $ popd 522 522 $ git worktree remove ../temp 523 523 ------------ 524 + 525 + CONFIGURATION 526 + ------------- 527 + 528 + include::includes/cmd-config-section-all.adoc[] 529 + 530 + include::config/worktree.adoc[] 524 531 525 532 BUGS 526 533 ----