From: Junio C Hamano Date: Thu, 01 May 2025 21:34:14 GMT Subject: [WIP PATCH 4/4] git-worktree doc: update mark-up of synopsis option descriptions Message-ID: <20250501213414.370514-5-gitster@pobox.com> In-Reply-To: <20250501213414.370514-1-gitster@pobox.com> To unify mark-up used in our documentation to a newer convention, started by 22293895 (doc: apply synopsis simplification on git-clone and git-init, 2024-09-24), update the documentation of 'git worktree' to * use [synopsis], not [verse] in the SYNOPSIS section * enclose `--option=` in backquotes Also, split '--[no-]option' into '--option' and '--no-option' to make it easier to grep for them. Signed-off-by: Junio C Hamano --- Documentation/git-worktree.adoc | 71 ++++++++++++++++++--------------- 1 file changed, 38 insertions(+), 33 deletions(-) diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc index 8340b7f028..46715cbef7 100644 --- a/Documentation/git-worktree.adoc +++ b/Documentation/git-worktree.adoc @@ -8,16 +8,16 @@ git-worktree - Manage multiple working trees SYNOPSIS -------- -[verse] -'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason ]] - [--orphan] [(-b | -B) ] [] -'git worktree list' [-v | --porcelain [-z]] -'git worktree lock' [--reason ] -'git worktree move' -'git worktree prune' [-n] [-v] [--expire ] -'git worktree remove' [-f] -'git worktree repair' [...] -'git worktree unlock' +[synopsis] +git worktree add [-f] [--detach] [--checkout] [--lock [--reason ]] + [--orphan] [(-b | -B) ] [] +git worktree list [-v | --porcelain [-z]] +git worktree lock [--reason ] +git worktree move +git worktree prune [-n] [-v] [--expire ] +git worktree remove [-f] +git worktree repair [...] +git worktree unlock DESCRIPTION ----------- @@ -169,8 +169,8 @@ Unlock a worktree, allowing it to be pruned, moved or deleted. OPTIONS ------- --f:: ---force:: +`-f`:: +`--force`:: By default, `add` refuses to create a new worktree when `` is a branch name and is already checked out by another worktree, or if `` is already assigned to some @@ -186,8 +186,8 @@ allows the move to proceed; use `--force` twice if the destination is locked. `remove` refuses to remove an unclean worktree unless `--force` is used. To remove a locked worktree, specify `--force` twice. --b :: --B :: +`-b `:: +`-B `:: With `add`, create a new branch named `` starting at ``, and check out `` into the new worktree. If `` is omitted, it defaults to `HEAD`. @@ -195,18 +195,20 @@ To remove a locked worktree, specify `--force` twice. exists. `-B` overrides this safeguard, resetting `` to ``. --d:: ---detach:: +`-d`:: +`--detach`:: With `add`, detach `HEAD` in the new worktree. See "DETACHED HEAD" in linkgit:git-checkout[1]. ---[no-]checkout:: +`--checkout`:: +`--no-checkout`:: By default, `add` checks out ``, however, `--no-checkout` can be used to suppress checkout in order to make customizations, such as configuring sparse-checkout. See "Sparse checkout" in linkgit:git-read-tree[1]. ---[no-]guess-remote:: +`--guess-remote`:: +`--no-guess-remote`:: With `worktree add `, without ``, instead of creating a new branch from `HEAD`, if there exists a tracking branch in exactly one remote matching the basename of ``, @@ -216,7 +218,8 @@ To remove a locked worktree, specify `--force` twice. This can also be set up as the default behaviour by using the `worktree.guessRemote` config option. ---[no-]relative-paths:: +`--relative-paths` +`--no-relative-paths`:: Link worktrees using relative paths or absolute paths (default). Overrides the `worktree.useRelativePaths` config option, see linkgit:git-config[1]. @@ -224,55 +227,57 @@ This can also be set up as the default behaviour by using the With `repair`, the linking files will be updated if there's an absolute/relative mismatch, even if the links are correct. ---[no-]track:: - When creating a new branch, if `` is a branch, +`--track`:: +`--no-track`:: + With `--track`, when creating a new branch, + if `` is a branch, mark it as "upstream" from the new branch. This is the default if `` is a remote-tracking branch. See `--track` in linkgit:git-branch[1] for details. ---lock:: +`--lock`:: Keep the worktree locked after creation. This is the equivalent of `git worktree lock` after `git worktree add`, but without a race condition. --n:: ---dry-run:: +`-n`:: +`--dry-run`:: With `prune`, do not remove anything; just report what it would remove. ---orphan:: +`--orphan`:: With `add`, make the new worktree and index empty, associating the worktree with a new unborn branch named ``. ---porcelain:: +`--porcelain`:: With `list`, output in an easy-to-parse format for scripts. This format will remain stable across Git versions and regardless of user configuration. It is recommended to combine this with `-z`. See below for details. --z:: +`-z`:: Terminate each line with a NUL rather than a newline when `--porcelain` is specified with `list`. This makes it possible to parse the output when a worktree path contains a newline character. --q:: ---quiet:: +`-q`:: +`--quiet`:: With `add`, suppress feedback messages. --v:: ---verbose:: +`-v`:: +`--verbose`:: With `prune`, report all removals. + With `list`, output additional information about worktrees (see below). ---expire