From: Junio C Hamano <hidden> Date: 2016-06-25 19:45:22
Barret Rennie [off-list ref] writes:
quoted
What is "the name for the worktree"? Is it the directory where it lives in?
Is it how it is listed with 'git worktree list'?
The name of the worktree is the name of the created directory in
`.git/worktrees`.
quoted
How is --name different from the <path> argument?
Currently, if you run:
git worktree add /my/worktree/checkout <branch>
you get a worktree "named" checkout, i.e., `.git/worktrees/checkout`. The
idea with this patch is to allow you use a more specific name when you would
otherwise have mulitiple worktrees of the form `checkout`, `checkout1`, etc.
That is, you could do
git worktree add --name branch1 /worktrees/branch1/src branch1
git worktree add --name branch2 /worktrees/branch2/src branch2
git worktree add --name branch3 /worktrees/branch3/src branch3
and have `.git/worktrees/branch1`, `.git/worktrees/branch2` and
`.git/worktrees/branch3` instead of `.git/worktrees/src`,
`.git/worktrees/src1`, `.git/worktrees/src2`. That way, it becomes more clear
when poking inside `.git/worktrees` which directory points to which checkout.
That is a way better justification of "why we need to use a custom
name, not the default one" than the previous "with this we can use a
custom name".
As long as you can justify why having anything underneath branch$n/
is necessary, that is. In your explanation above, it is still
unclear why you need a checkout at /worktrees/branch$n/src/, and why
it would not work if it is at /worktrees/branch$n/.
Note that I am not saying "there cannot be a good reason, do not add
this feature" when I say "it is unclear why". I am encouraging you
and others in this discussion thread to find good use cases for the
proposed new feature and come up with materials to help improving
the documentation part of the patch. That way, the users with
similar needs can find how the feature is supposed to be used and
understand the feature better.
I suspect that this new feature might be useful when two more more
interdependent projects (they could be organized as submodules in a
superproject, but they can be independent checkouts of different
projects) are used together. Imagine frotz and nitfol projects, and
without fancier setup to have multiple checkouts, you may be
expected (by these two projects) to check them out like so:
$top/frotz/
$top/libs/nitfol/
where $top can be anywhere but to clarify the line of thought, lets
pick a concrete place, say $HOME/xyzzy. So without worktrees, you
would have
$HOME/xyzzy/frotz
$HOME/xyzzy/libs/nitfol
Now, if you do the worktree, you may still want the relative
structure between these two, i.e. if you want to work on two
different branch combinations of the whole thing, you would want to
do this:
$HOME/xyzzy-1/frotz - borrow from $HOME/xyzzy/frotz
$HOME/xyzzy-1/libs/nitfol - likewise for nitfol
$HOME/xyzzy-2/frotz - borrow from $HOME/xyzzy/frotz
$HOME/xyzzy-2/libs/nitfol - likewise for nitfol
where xyzzy-$n may be for topic-$n branch both in frotz and nitfol.
And explained that way, it becomes clearer that you would want to
name $HOME/xyzzy-1/frotz worktree after "topic-1", not the default
name you would get "frotz" (because the default gives you the leaf
level name of the newly created worktree).
After the discussion above (which may or may not match what you
raised this topic for), I think a feature to let you override the
default name makes sense.
It just needs to be explained better to help the users when the
feature eventually becomes part of Git. Also, others (especially
Duy) may have even better ideas (e.g. instead of having to always
use --name to give custom name for all worktrees, set a "hint" just
once to help the logic that comes up with the default name give a
better name), so while the feature may be desirable, your exact
implementation may or may not be what we eventually want to adopt.
Thanks.
On Jun 25, 2016, at 1:45 PM, Junio C Hamano [off-list ref] wrote:
Barret Rennie [off-list ref] writes:
quoted
quoted
What is "the name for the worktree"? Is it the directory where it lives in?
Is it how it is listed with 'git worktree list'?
The name of the worktree is the name of the created directory in
`.git/worktrees`.
quoted
How is --name different from the <path> argument?
Currently, if you run:
git worktree add /my/worktree/checkout <branch>
you get a worktree "named" checkout, i.e., `.git/worktrees/checkout`. The
idea with this patch is to allow you use a more specific name when you would
otherwise have mulitiple worktrees of the form `checkout`, `checkout1`, etc.
That is, you could do
git worktree add --name branch1 /worktrees/branch1/src branch1
git worktree add --name branch2 /worktrees/branch2/src branch2
git worktree add --name branch3 /worktrees/branch3/src branch3
and have `.git/worktrees/branch1`, `.git/worktrees/branch2` and
`.git/worktrees/branch3` instead of `.git/worktrees/src`,
`.git/worktrees/src1`, `.git/worktrees/src2`. That way, it becomes more clear
when poking inside `.git/worktrees` which directory points to which checkout.
That is a way better justification of "why we need to use a custom
name, not the default one" than the previous "with this we can use a
custom name".
As long as you can justify why having anything underneath branch$n/
is necessary, that is. In your explanation above, it is still
unclear why you need a checkout at /worktrees/branch$n/src/, and why
it would not work if it is at /worktrees/branch$n/.
That was a less-than-concrete example, I'll grant you. I do follow the method
you suggest below for the projects I maintain with this workflow.
Note that I am not saying "there cannot be a good reason, do not add
this feature" when I say "it is unclear why". I am encouraging you
and others in this discussion thread to find good use cases for the
proposed new feature and come up with materials to help improving
the documentation part of the patch. That way, the users with
similar needs can find how the feature is supposed to be used and
understand the feature better.
I suspect that this new feature might be useful when two more more
interdependent projects (they could be organized as submodules in a
superproject, but they can be independent checkouts of different
projects) are used together. Imagine frotz and nitfol projects, and
without fancier setup to have multiple checkouts, you may be
expected (by these two projects) to check them out like so:
$top/frotz/
$top/libs/nitfol/
where $top can be anywhere but to clarify the line of thought, lets
pick a concrete place, say $HOME/xyzzy. So without worktrees, you
would have
$HOME/xyzzy/frotz
$HOME/xyzzy/libs/nitfol
Now, if you do the worktree, you may still want the relative
structure between these two, i.e. if you want to work on two
different branch combinations of the whole thing, you would want to
do this:
$HOME/xyzzy-1/frotz - borrow from $HOME/xyzzy/frotz
$HOME/xyzzy-1/libs/nitfol - likewise for nitfol
$HOME/xyzzy-2/frotz - borrow from $HOME/xyzzy/frotz
$HOME/xyzzy-2/libs/nitfol - likewise for nitfol
where xyzzy-$n may be for topic-$n branch both in frotz and nitfol.
And explained that way, it becomes clearer that you would want to
name $HOME/xyzzy-1/frotz worktree after "topic-1", not the default
name you would get "frotz" (because the default gives you the leaf
level name of the newly created worktree).
After the discussion above (which may or may not match what you
raised this topic for), I think a feature to let you override the
default name makes sense.
It just needs to be explained better to help the users when the
feature eventually becomes part of Git. Also, others (especially
Duy) may have even better ideas (e.g. instead of having to always
use --name to give custom name for all worktrees, set a "hint" just
once to help the logic that comes up with the default name give a
better name), so while the feature may be desirable, your exact
implementation may or may not be what we eventually want to adopt.
Would you like me to re-submit this with a more detailed
explanation in the commit message? Also, I agree that always having
to use `--name` to set a custom name could be possibly cumbersome.
An alternate way I can think of would be to a config option such as
`worktree.nameHint` which would let you set the kind of name you'd
like for your worktrees, say `default` (the current behaviour) or
`branch` (where it would be named <topic-branch><n>).
The only issue I have with that is I maintain two projects that
have a dependency on the same version of a library. My current
project directory looks like the following:
projects/reviewboard/branches/
2.5.x/
reviewboard/ # Version 2.0
djblets/ # Version 0.8
3.0.x/
reviewboard/ # Version 3.0
djblets/ # Version 0.10
projects/splat/src/
splat/ # master checkout
djblets/ # Version 0.10
If we used some sort of hint system, I'd end up with two worktrees
named something like `release-0.10.x` and `release-0.10.x1`, which
is better than the current situation, but still not ideal for my
use case.
If someone suggests a better scheme for naming the worktrees, I'd
be happy to rewrite this patch to use it.
From: Eric Sunshine <hidden> Date: 2016-06-26 23:00:31
On Sat, Jun 25, 2016 at 3:45 PM, Junio C Hamano [off-list ref] wrote:
[...snip...]
And explained that way, it becomes clearer that you would want to
name $HOME/xyzzy-1/frotz worktree after "topic-1", not the default
name you would get "frotz" (because the default gives you the leaf
level name of the newly created worktree).
After the discussion above (which may or may not match what you
raised this topic for), I think a feature to let you override the
default name makes sense.
One thing which hasn't been explained, and about which I'm still
confused even after reading this thread in its entirety, is what
Barret means when he says that he "breaks" his worktrees. What is the
nature of this breakage? Depending upon that answer, would "git
rev-parse --git-dir" be sufficient for your needs? Or, would "git
worktree list" be able to give you the desired information? (As
envisioned, "git worktree list" was intended to provide much more
information than it currently does, such as the .git/worktree dir
name, and such an enhancement might be welcome.)
On Jun 26, 2016, at 5:00 PM, Eric Sunshine [off-list ref] wrote:
On Sat, Jun 25, 2016 at 3:45 PM, Junio C Hamano [off-list ref] wrote:
quoted
[...snip...]
And explained that way, it becomes clearer that you would want to
name $HOME/xyzzy-1/frotz worktree after "topic-1", not the default
name you would get "frotz" (because the default gives you the leaf
level name of the newly created worktree).
After the discussion above (which may or may not match what you
raised this topic for), I think a feature to let you override the
default name makes sense.
One thing which hasn't been explained, and about which I'm still
confused even after reading this thread in its entirety, is what
Barret means when he says that he "breaks" his worktrees. What is the
nature of this breakage? Depending upon that answer, would "git
rev-parse --git-dir" be sufficient for your needs? Or, would "git
worktree list" be able to give you the desired information? (As
envisioned, "git worktree list" was intended to provide much more
information than it currently does, such as the .git/worktree dir
name, and such an enhancement might be welcome.)
My worktree breakages are usually the result of my reorganizing my projects,
usually because a branch changes name (for example, if branch release-1 gets
pushed back to release-2). Then I go and rename all my directories and git
gets unhappy and I have to manually fix them or re-create the worktrees.
Having `git worktree list` give the worktree directory would be very useful,
but I still would like the ability to change the name of a worktree.
From: Eric Sunshine <hidden> Date: 2016-06-27 23:11:41
On Mon, Jun 27, 2016 at 1:52 AM, Barret Rennie [off-list ref] wrote:
On Jun 26, 2016, at 5:00 PM, Eric Sunshine [off-list ref] wrote:
quoted
One thing which hasn't been explained, and about which I'm still
confused even after reading this thread in its entirety, is what
Barret means when he says that he "breaks" his worktrees. What is the
nature of this breakage? Depending upon that answer, would "git
rev-parse --git-dir" be sufficient for your needs? Or, would "git
worktree list" be able to give you the desired information? (As
envisioned, "git worktree list" was intended to provide much more
information than it currently does, such as the .git/worktree dir
name, and such an enhancement might be welcome.)
My worktree breakages are usually the result of my reorganizing my projects,
usually because a branch changes name (for example, if branch release-1 gets
pushed back to release-2). Then I go and rename all my directories and git
gets unhappy and I have to manually fix them or re-create the worktrees.
Quoting from your earlier email justifying why you consider this patch
desirable:
...when I break my worktrees and can’t figure out
which worktree dir is the one I’ve broken.
But, doesn't "git rev-parse --git-dir" from within a "broken" worktree
answer that question? Or, wouldn't an enhanced "git worktree list"
answer the question from the opposite side?
Having `git worktree list` give the worktree directory would be very useful,
but I still would like the ability to change the name of a worktree.
My knee-jerk reaction is that the directory name under .git/worktrees
is an implementation detail (and could easily have been an arbitrary
ID, such as .git/worktrees/7ba84ec0) and rather than exposing it
further and encouraging people to muck around in it manually, we
should be providing higher-level solutions so that they don't have to.
Even without the higher-level solutions, it seems like "git rev-parse
--git-dir" should satisfy your needs, and if someone enhances "git
worktree list" to provide the additional worktree tag name (as
envisioned all along), then you'd likewise have sufficient information
to "fix" your worktrees.
As an example of higher-level solutions, Duy's "git worktree move"
series[1] would, I think, be exactly what you need to avoid such
breakage in the first place (assuming you can retrain your fingers or
fix your scripts, if they are doing the worktree renaming).
I don't know how Duy and Junio feel about it, but my response to this
patch and what it wants to accomplish (even with Junio's input) is
fairly negative. I'd much rather see more missing high-level worktree
features implemented rather than see patches further exposing
git-worktree's internals.
[1]: http://thread.gmane.org/gmane.comp.version-control.git/298194
On Jun 27, 2016, at 5:11 PM, Eric Sunshine [off-list ref] wrote:
[snip]
My knee-jerk reaction is that the directory name under .git/worktrees
is an implementation detail (and could easily have been an arbitrary
ID, such as .git/worktrees/7ba84ec0) and rather than exposing it
further and encouraging people to muck around in it manually, we
should be providing higher-level solutions so that they don't have to.
Even without the higher-level solutions, it seems like "git rev-parse
--git-dir" should satisfy your needs, and if someone enhances "git
worktree list" to provide the additional worktree tag name (as
envisioned all along), then you'd likewise have sufficient information
to "fix" your worktrees.
As an example of higher-level solutions, Duy's "git worktree move"
series[1] would, I think, be exactly what you need to avoid such
breakage in the first place (assuming you can retrain your fingers or
fix your scripts, if they are doing the worktree renaming).
I don't know how Duy and Junio feel about it, but my response to this
patch and what it wants to accomplish (even with Junio's input) is
fairly negative. I'd much rather see more missing high-level worktree
features implemented rather than see patches further exposing
git-worktree's internals.
[1]: http://thread.gmane.org/gmane.comp.version-control.git/298194
Yes, it does seem like `git worktree move` will solve all my issues and
is a much more elegant solution. Thanks for pointing it out to me and
looking at this patch.
I may write a patch to print out the worktree tag name instead and submit
that later.
Regards,
Barret Rennie