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=<value>` 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 <gitster@xxxxxxxxx> --- 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 <string>]] - [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>] -'git worktree list' [-v | --porcelain [-z]] -'git worktree lock' [--reason <string>] <worktree> -'git worktree move' <worktree> <new-path> -'git worktree prune' [-n] [-v] [--expire <expire>] -'git worktree remove' [-f] <worktree> -'git worktree repair' [<path>...] -'git worktree unlock' <worktree> +[synopsis] +git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]] + [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>] +git worktree list [-v | --porcelain [-z]] +git worktree lock [--reason <string>] <worktree> +git worktree move <worktree> <new-path> +git worktree prune [-n] [-v] [--expire <expire>] +git worktree remove [-f] <worktree> +git worktree repair [<path>...] +git worktree unlock <worktree> 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 `<commit-ish>` is a branch name and is already checked out by another worktree, or if `<path>` 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 <new-branch>:: --B <new-branch>:: +`-b <new-branch>`:: +`-B <new-branch>`:: With `add`, create a new branch named `<new-branch>` starting at `<commit-ish>`, and check out `<new-branch>` into the new worktree. If `<commit-ish>` is omitted, it defaults to `HEAD`. @@ -195,18 +195,20 @@ To remove a locked worktree, specify `--force` twice. exists. `-B` overrides this safeguard, resetting `<new-branch>` to `<commit-ish>`. --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 `<commit-ish>`, 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 <path>`, without `<commit-ish>`, instead of creating a new branch from `HEAD`, if there exists a tracking branch in exactly one remote matching the basename of `<path>`, @@ -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 `<commit-ish>` is a branch, +`--track`:: +`--no-track`:: + With `--track`, 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. ---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 `<new-branch>`. ---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 <time>:: +`--expire <time>`:: With `prune`, only expire unused worktrees older than `<time>`. + With `list`, annotate missing worktrees as prunable if they are older than `<time>`. ---reason <string>:: +`--reason <string>`:: With `lock` or with `add --lock`, an explanation why the worktree is locked. -- 2.49.0-599-g90c2cffacf
