From: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
To: Eric Sunshine <sunshine@sunshineco.com>
Cc: Jacob Abel <jacobabel@nullpo.dev>,
git@vger.kernel.org, Taylor Blau <me@ttaylorr.com>
Subject: Re: [PATCH v3 2/2] worktree add: add --orphan flag
Date: Tue, 15 Nov 2022 23:35:51 +0100 [thread overview]
Message-ID: <221116.86a64rkdcj.gmgdl@evledraar.gmail.com> (raw)
In-Reply-To: <CAPig+cRuJVN2Hc-oNF10sx=ZzArb8skXUQ8m5Qek2e-o4c9VEg@mail.gmail.com>
On Tue, Nov 15 2022, Eric Sunshine wrote:
> On Tue, Nov 15, 2022 at 4:13 PM Ævar Arnfjörð Bjarmason
> <avarab@gmail.com> wrote:
>> On Thu, Nov 10 2022, Jacob Abel wrote:
>> > Adds support for creating an orphan branch when adding a new worktree.
>> > This functionality is equivalent to git switch's --orphan flag.
>> >
>> > The original reason this feature was implemented was to allow a user
>> > to initialise a new repository using solely the worktree oriented
>> > workflow. Example usage included below.
>> >
>> > $ GIT_DIR=".git" git init --bare
>> > $ git worktree add --orphan master master/
>> >
>> > Signed-off-by: Jacob Abel <jacobabel@nullpo.dev>
>> > ---
>> > +Create a worktree containing an orphan branch named `<branch>` with a
>> > +clean working directory. See `--orphan` in linkgit:git-switch[1] for
>> > +more details.
>>
>> Seeing as "git switch" is still marked "EXPERIMENTAL", it may be prudent
>> in general to avoid linking to it in lieu of "git checkout".
>>
>> In this case in particular though the "more details" are almost
>> completely absent from the "git-switch" docs, and they don't (which is
>> their won flaw) link to the more detailed "git-checkout" docs.
>>
>> But for this patch, it seems much better to link to the "checkout" docs,
>> no?
>
> Sorry, no. The important point here is that the --orphan option being
> added to `git worktree add` closely follows the behavior of `git
> switch --orphan`, which is quite different from the behavior of `git
> checkout --orphan`.
>
> The `git switch --orphan` documentation doesn't seem particularly
> lacking; it correctly describes the (very) simplified behavior of that
> command over `git checkout --orphan`. I might agree that there isn't
> much reason to link to git-switch for "more details", though, since
> there isn't really anything else that needs to be said.
Aside from what it says now: 1/2 of what I'm saying is that linking to
it while it says it's "EXPERIMENTAL" might be either jumping the gun.
Or maybe we should just declare it non-"EXPERIMENTAL", but in any case
this unrelated topic might want to avoid that altogether and just link
to the "checkout" version.
A quick grep of our docs (for linkgit:git-switch) that this would be the
first mention outside of user-manual.txt where we link to it when it's
not in the context of "checkout or switch", or where we're explaining
something switch-specific (i.e. the "suggestDetachingHead" advice).
Having said that I don't really care, just a suggestion...
> If we did want to say something else here, we might copy one sentence
> from the `git checkout --orphan` documentation:
>
> The first commit made on this new branch will have no parents and
> it will be the root of a new history totally disconnected from all
> the other branches and commits.
>
> The same sentence could be added to `git switch --orphan`
> documentation, but that's outside the scope of this patch series (thus
> can be done later by someone).
I think I was partially confused by skimming the SYNOPSIS and thinking
this supported <start-point> like checkout, which as I found in
https://lore.kernel.org/git/221115.86edu3kfqz.gmgdl@evledraar.gmail.com/
just seems to be a missing assertion where we want to die() if that's
provided in this mode.
What I also found a bit confusing (but maybe it's just me) is that the
"with a clean working directory" seemed at first to be drawing a
distinction between this behavior and that of "git switch", but from
poking at it some more it seems to be expressing "this is like git
switch's --orphan" with that.
I think instead of "clean working tree" it would be better to talk about
"tracked files", as "git switch --orphan" does, which AFAICT is what it
means. But then again the reason "switch" does that is because you have
*existing* tracked files, which inherently doesn't apply for "worktree".
Hrm.
So, I guess it depends on your mental model of this operation, but at
least I think it's more intuitive to explain it in terms of "git
checkout --orphan", not "git switch --orphan". I.e.:
Create a worktree containing an orphan branch named
`<branch>`. This works like linkgit:git-checkout[1]'s `--orphan'
option, except '<start-point>` isn't supported, and the "clear
the index" doesn't apply (as "worktree add" will always have a
new index)".
Whereas defining this in terms of git-switch's "All tracked files are
removed" might just be more confusing. What files? Since it's "worktree
add" there weren't any in the first place.
Anyway, I don't mind it as it is, but maybe the above write-up helps for
#leftoverbits if we ever want to unify these docs. I.e. AFAICT we could:
* Link from git-worktree to git-checkout, saying the above
* Link from git-switch to git-checkout, ditto, but that we also "remove
tracked files [of the current HEAD]".
>> > +test_expect_success '"add" --orphan/-b mutually exclusive' '
>> > + test_must_fail git worktree add --orphan poodle -b poodle bamboo
>> > +'
>> > +
>> > +test_expect_success '"add" --orphan/-B mutually exclusive' '
>> > + test_must_fail git worktree add --orphan poodle -B poodle bamboo
>> > +'
>> > +
>> > +test_expect_success '"add" --orphan/--detach mutually exclusive' '
>> > + test_must_fail git worktree add --orphan poodle --detach bamboo
>> > +'
>> > +
>> > +test_expect_success '"add" --orphan/--no-checkout mutually exclusive' '
>> > + test_must_fail git worktree add --orphan poodle --no-checkout bamboo
>> > +'
>> > +
>> > +test_expect_success '"add" -B/--detach mutually exclusive' '
>> > + test_must_fail git worktree add -B poodle --detach bamboo main
>> > +'
>> > +
>>
>> This would be much better as a for-loop:
>>
>> for opt in -b -B ...
>> do
>> test_expect_success "...$opt" '<test here, uses $opt>'
>> done
>>
>> Note the ""-quotes for the description, and '' for the test, that's not
>> a mistake, we eval() the latter.
>
> Such a loop would need to be more complex than this, wouldn't it, to
> account for all the combinations? I'd normally agree about the loop,
> but given that it requires extra complexity, I don't really mind
> seeing the individual tests spelled out manually in this case; they're
> dead simple to understand as written. I don't feel strongly either
> way, but I also don't want to ask for extra work from the patch author
> for a subjective change.
Yeah, it's probably not worth it. This is partially cleaning up existing
tests, but maybe:
diff --git a/t/t2400-worktree-add.sh b/t/t2400-worktree-add.sh
index 93c340f4aff..5acfd48f418 100755
--- a/t/t2400-worktree-add.sh
+++ b/t/t2400-worktree-add.sh
@@ -298,37 +298,21 @@ test_expect_success '"add" no auto-vivify with --detach and <branch> omitted' '
test_must_fail git -C mish/mash symbolic-ref HEAD
'
-test_expect_success '"add" -b/-B mutually exclusive' '
- test_must_fail git worktree add -b poodle -B poodle bamboo main
-'
-
-test_expect_success '"add" -b/--detach mutually exclusive' '
- test_must_fail git worktree add -b poodle --detach bamboo main
-'
-
-test_expect_success '"add" -B/--detach mutually exclusive' '
- test_must_fail git worktree add -B poodle --detach bamboo main
-'
-
-test_expect_success '"add" --orphan/-b mutually exclusive' '
- test_must_fail git worktree add --orphan poodle -b poodle bamboo
-'
-
-test_expect_success '"add" --orphan/-B mutually exclusive' '
- test_must_fail git worktree add --orphan poodle -B poodle bamboo
-'
-
-test_expect_success '"add" --orphan/--detach mutually exclusive' '
- test_must_fail git worktree add --orphan poodle --detach bamboo
-'
-
-test_expect_success '"add" --orphan/--no-checkout mutually exclusive' '
- test_must_fail git worktree add --orphan poodle --no-checkout bamboo
-'
-
-test_expect_success '"add" -B/--detach mutually exclusive' '
- test_must_fail git worktree add -B poodle --detach bamboo main
-'
+test_wt_add_excl() {
+ local opts="$@" &&
+ test_expect_success "'worktree add' with '$opts' has mutually exclusive options" '
+ test_must_fail git worktree add $opts
+ '
+}
+test_wt_add_excl -b poodle -B poodle bamboo main
+test_wt_add_excl -b poodle --orphan poodle bamboo
+test_wt_add_excl -b poodle --detach bamboo main
+test_wt_add_excl -B poodle --detach bamboo main
+test_wt_add_excl -B poodle --detach bamboo main
+test_wt_add_excl -B poodle --orphan poodle bamboo
+test_wt_add_excl --orphan poodle --detach bamboo
+test_wt_add_excl --orphan poodle --no-checkout bamboo
+test_wt_add_excl --orphan poodle bamboo main
test_expect_success '"add -B" fails if the branch is checked out' '
git rev-parse newmain >before &&
I re-arranged that a bit, but probably not worth a loop. I *did* spot in
doing that that if I sort the options I end up with a duplicate test,
i.e. we test "-B poodle --detach bamboo main" twice.
That seems to be added by mistake in 2/2, i.e. it's the existing test
you can see in the diff context, just added at the end.
next prev parent reply other threads:[~2022-11-15 23:28 UTC|newest]
Thread overview: 129+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-11-04 1:02 [PATCH 0/4] worktree: Support `--orphan` when creating new worktrees Jacob Abel
2022-11-04 1:03 ` [PATCH 1/4] worktree add: Include -B in usage docs Jacob Abel
2022-11-04 3:05 ` Eric Sunshine
2022-11-04 4:24 ` Jacob Abel
2022-11-04 1:03 ` [PATCH 2/4] builtin/worktree.c: Update checkout_worktree() to use git-worktree Jacob Abel
2022-11-04 1:32 ` Ævar Arnfjörð Bjarmason
2022-11-04 3:58 ` Jacob Abel
2022-11-04 20:45 ` Taylor Blau
2022-11-04 1:03 ` [PATCH 3/4] worktree add: add --orphan flag Jacob Abel
2022-11-04 1:33 ` Ævar Arnfjörð Bjarmason
2022-11-04 4:11 ` Jacob Abel
2022-11-04 5:03 ` Eric Sunshine
2022-11-04 16:41 ` Jacob Abel
2022-11-10 4:13 ` Eric Sunshine
2022-11-10 21:21 ` Jacob Abel
2022-11-04 1:03 ` [PATCH 4/4] worktree add: Add unit tests for --orphan Jacob Abel
2022-11-04 1:37 ` Ævar Arnfjörð Bjarmason
2022-11-04 4:17 ` Jacob Abel
2022-11-04 4:33 ` [PATCH 0/4] worktree: Support `--orphan` when creating new worktrees Eric Sunshine
2022-11-04 4:47 ` Jacob Abel
2022-11-04 4:50 ` Jacob Abel
2022-11-04 21:34 ` [PATCH v2 0/2] " Jacob Abel
2022-11-04 21:34 ` [PATCH v2 1/2] worktree add: Include -B in usage docs Jacob Abel
2022-11-04 21:34 ` [PATCH v2 2/2] worktree add: add --orphan flag Jacob Abel
2022-11-10 23:32 ` [PATCH v3 0/2] worktree: Support `--orphan` when creating new worktrees Jacob Abel
2022-11-10 23:32 ` [PATCH v3 1/2] worktree add: Include -B in usage docs Jacob Abel
2022-11-10 23:32 ` [PATCH v3 2/2] worktree add: add --orphan flag Jacob Abel
2022-11-15 21:08 ` Ævar Arnfjörð Bjarmason
2022-11-15 21:29 ` Eric Sunshine
2022-11-15 22:35 ` Ævar Arnfjörð Bjarmason [this message]
2022-11-16 0:19 ` Eric Sunshine
2022-11-19 3:13 ` Jacob Abel
2022-11-19 3:09 ` Jacob Abel
2022-11-19 11:50 ` Ævar Arnfjörð Bjarmason
2022-11-19 1:44 ` Jacob Abel
2022-11-22 6:00 ` Eric Sunshine
2022-11-22 23:09 ` Jacob Abel
2022-11-15 22:09 ` Ævar Arnfjörð Bjarmason
2022-11-19 2:57 ` Jacob Abel
2022-11-19 11:50 ` Ævar Arnfjörð Bjarmason
2022-11-16 0:39 ` [PATCH v3 0/2] worktree: Support `--orphan` when creating new worktrees Eric Sunshine
2022-11-17 10:00 ` Ævar Arnfjörð Bjarmason
2022-11-19 3:47 ` Jacob Abel
2022-11-19 11:48 ` Ævar Arnfjörð Bjarmason
2022-11-22 5:16 ` Eric Sunshine
2022-11-22 23:26 ` Jacob Abel
2022-11-22 23:55 ` Ævar Arnfjörð Bjarmason
2022-11-23 2:47 ` Jacob Abel
2022-11-23 2:43 ` Rubén Justo
2022-11-23 5:37 ` Jacob Abel
2022-11-23 7:35 ` Rubén Justo
2022-11-22 14:45 ` Phillip Wood
2022-11-23 4:21 ` Jacob Abel
2022-12-12 1:42 ` [PATCH v4 0/3] " Jacob Abel
2022-12-12 1:42 ` [PATCH v4 1/3] worktree add: Include -B in usage docs Jacob Abel
2022-12-12 1:42 ` [PATCH v4 2/3] worktree add: add --orphan flag Jacob Abel
2022-12-12 8:11 ` Ævar Arnfjörð Bjarmason
2022-12-12 14:55 ` Jacob Abel
2022-12-12 18:14 ` Ævar Arnfjörð Bjarmason
2022-12-12 22:39 ` Jacob Abel
2022-12-12 1:43 ` [PATCH v4 3/3] worktree add: Add hint to use --orphan when bad ref Jacob Abel
2022-12-12 8:35 ` Ævar Arnfjörð Bjarmason
2022-12-12 14:59 ` Jacob Abel
2022-12-12 18:16 ` Ævar Arnfjörð Bjarmason
2022-12-12 18:35 ` Eric Sunshine
2022-12-12 22:36 ` Jacob Abel
2022-12-12 22:38 ` Jacob Abel
2022-12-20 2:37 ` [PATCH v5 0/4] worktree: Support `--orphan` when creating new worktrees Jacob Abel
2022-12-20 2:37 ` [PATCH v5 1/4] worktree add: Include -B in usage docs Jacob Abel
2022-12-20 3:42 ` Junio C Hamano
2022-12-20 23:24 ` Jacob Abel
2022-12-20 2:37 ` [PATCH v5 2/4] worktree add: refactor opt exclusion tests Jacob Abel
2022-12-20 4:00 ` Junio C Hamano
2022-12-20 23:29 ` Jacob Abel
2022-12-20 2:38 ` [PATCH v5 3/4] worktree add: add --orphan flag Jacob Abel
2022-12-20 4:19 ` Junio C Hamano
2022-12-21 0:17 ` Jacob Abel
2022-12-20 2:38 ` [PATCH v5 4/4] worktree add: Add hint to use --orphan when bad ref Jacob Abel
2022-12-20 6:18 ` Junio C Hamano
2022-12-21 0:42 ` Jacob Abel
2022-12-28 6:16 ` [PATCH v6 0/4] worktree: Support `--orphan` when creating new worktrees Jacob Abel
2022-12-28 6:16 ` [PATCH v6 1/4] worktree add: include -B in usage docs Jacob Abel
2022-12-28 6:16 ` [PATCH v6 2/4] worktree add: refactor opt exclusion tests Jacob Abel
2022-12-28 12:54 ` Junio C Hamano
2022-12-29 6:51 ` Jacob Abel
2022-12-29 10:07 ` Junio C Hamano
2022-12-29 20:48 ` Jacob Abel
2023-01-06 6:31 ` Jacob Abel
2023-01-06 12:34 ` Junio C Hamano
2023-01-07 4:45 ` Jacob Abel
2022-12-28 6:17 ` [PATCH v6 3/4] worktree add: add --orphan flag Jacob Abel
2022-12-28 6:17 ` [PATCH v6 4/4] worktree add: add hint to direct users towards --orphan Jacob Abel
2023-01-06 14:19 ` Phillip Wood
2022-12-28 8:01 ` [PATCH v6 0/4] worktree: Support `--orphan` when creating new worktrees Ævar Arnfjörð Bjarmason
2022-12-29 6:38 ` Jacob Abel
2022-12-29 10:42 ` Ævar Arnfjörð Bjarmason
2022-12-29 21:22 ` Jacob Abel
2023-01-07 4:58 ` [PATCH v7 " Jacob Abel
2023-01-07 4:59 ` [PATCH v7 1/4] worktree add: include -B in usage docs Jacob Abel
2023-01-07 4:59 ` [PATCH v7 2/4] worktree add: refactor opt exclusion tests Jacob Abel
2023-01-08 7:13 ` Junio C Hamano
2023-01-08 15:08 ` Jacob Abel
2023-01-07 4:59 ` [PATCH v7 3/4] worktree add: add --orphan flag Jacob Abel
2023-01-07 4:59 ` [PATCH v7 4/4] worktree add: add hint to direct users towards --orphan Jacob Abel
2023-01-09 12:26 ` [PATCH v7 0/4] worktree: Support `--orphan` when creating new worktrees Ævar Arnfjörð Bjarmason
2023-01-09 17:11 ` Jacob Abel
2023-01-09 17:21 ` Ævar Arnfjörð Bjarmason
2023-01-09 17:26 ` Jacob Abel
2023-01-09 17:32 ` [PATCH v8 " Jacob Abel
2023-01-09 17:32 ` [PATCH v8 1/4] worktree add: include -B in usage docs Jacob Abel
2023-01-09 17:33 ` [PATCH v8 2/4] worktree add: refactor opt exclusion tests Jacob Abel
2023-01-09 17:33 ` [PATCH v8 3/4] worktree add: add --orphan flag Jacob Abel
2023-01-13 10:20 ` Phillip Wood
2023-01-13 17:32 ` Junio C Hamano
2023-01-14 22:47 ` Jacob Abel
2023-01-15 3:09 ` Junio C Hamano
2023-01-15 3:41 ` rsbecker
2023-01-15 3:49 ` Junio C Hamano
2023-01-18 22:46 ` 'Jacob Abel'
2023-01-18 22:18 ` Jacob Abel
2023-01-19 15:32 ` Ævar Arnfjörð Bjarmason
2023-01-19 16:32 ` Junio C Hamano
2023-01-16 10:47 ` Phillip Wood
2023-01-18 22:40 ` Jacob Abel
2023-01-19 16:18 ` Phillip Wood
2023-01-19 22:20 ` Jacob Abel
2023-01-09 17:33 ` [PATCH v8 4/4] worktree add: add hint to direct users towards --orphan Jacob Abel
2023-01-09 19:20 ` [PATCH v8 0/4] worktree: Support `--orphan` when creating new worktrees Ævar Arnfjörð Bjarmason
2023-01-13 17:34 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=221116.86a64rkdcj.gmgdl@evledraar.gmail.com \
--to=avarab@gmail.com \
--cc=git@vger.kernel.org \
--cc=jacobabel@nullpo.dev \
--cc=me@ttaylorr.com \
--cc=sunshine@sunshineco.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).