On Fri, Feb 1, 2019 at 8:17 AM Duy Nguyen <[email protected]> wrote:
> I'm not going to bother you with code yet (although if you want, you
> can check out branch worktree-name on my gitlab repo), but this is
> what the user facing changes look like. Looking good?
>
> -- 8< --
> diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
> @@ -9,7 +9,7 @@ git-worktree - Manage multiple working trees
> SYNOPSIS
> +'git worktree add' [-f] [--detach] [--checkout] [--lock] [-b <new-branch>]
> [--name <name>] <path> [<commit-ish>]
> @@ -195,6 +195,13 @@ This can also be set up as the default behaviour by
> using the
> +--name <name>::
> + Name of the working tree. Each working tree must have a unique
> + name. This is also the directory name containing all working
> + tree's specific information under `$GIT_COMMON_DIR/worktrees`.
> + If `--name` is not given, the name is based on basename(3)
> + optionally with a number suffix to make it unique.
I think the "DETAILS" section also needs to be updated. It presently says:
The private sub-directory’s name is usually the base name of the
linked working tree’s path, possibly appended with a number to
make it unique.
Perhaps amend it to:
...to make it unique, or the name provided by `--name`.
> Porcelain Format
> ~~~~~~~~~~~~~~~~
> The porcelain format has a line per attribute. Attributes are listed with a
> @@ -341,10 +352,12 @@ $ git worktree list --porcelain
> worktree /path/to/bare-source
> bare
>
> +name linked
> worktree /path/to/linked-worktree
> HEAD abcd1234abcd1234abcd1234abcd1234abcd1234
> branch refs/heads/master
>
> +name other
> worktree /path/to/other-linked-worktree
> HEAD 1234abc1234abc1234abc1234abc1234abc1234a
> detached
Unfortunately, this will likely break existing tools. When I had
outlined the proposed porcelain format, my suggestion was that a
"worktree" line would indicate the start of a new stanza (with no
blank line), however, as it eventually got implemented (not by me),
that recommendation wasn't quite followed. Instead, what has been
documented "officially" in the git-worktree man-page is that each
stanza will start with a "worktree" line and that there will be a
blank line between stanzas. So, the new "name" line will need to be
placed somewhere after the "worktree" line in order to avoid tool
breakage.
