From: Duy Nguyen <email@example.com>
To: Elijah Newren <firstname.lastname@example.org>
Cc: "Ævar Arnfjörð Bjarmason" <email@example.com>,
"Git Mailing List" <firstname.lastname@example.org>,
"Junio C Hamano" <email@example.com>,
"Stefan Beller" <firstname.lastname@example.org>,
"Thomas Gummerer" <email@example.com>,
"Stefan Xenos" <firstname.lastname@example.org>
Subject: Re: [PATCH v3 07/14] checkout: split into switch-branch and restore-files
Date: Tue, 4 Dec 2018 19:17:39 +0100 [thread overview]
Message-ID: <CACsJy8D9Rgsf-E6yweQxpopFaOVZ1bgihEbg200yS1gup+Gt7Q@mail.gmail.com> (raw)
On Tue, Dec 4, 2018 at 6:43 PM Elijah Newren <email@example.com> wrote:
> > > > +--ours::
> > > > +--theirs::
> > > > + Check out stage #2 ('ours') or #3 ('theirs') for unmerged
> > > > + paths.
> > > > ++
> > > > +Note that during `git rebase` and `git pull --rebase`, 'ours' and
> > > > +'theirs' may appear swapped; `--ours` gives the version from the
> > > > +branch the changes are rebased onto, while `--theirs` gives the
> > > > +version from the branch that holds your work that is being rebased.
> > > > ++
> > > > +This is because `rebase` is used in a workflow that treats the
> > > > +history at the remote as the shared canonical one, and treats the
> > > > +work done on the branch you are rebasing as the third-party work to
> > > > +be integrated, and you are temporarily assuming the role of the
> > > > +keeper of the canonical history during the rebase. As the keeper of
> > > > +the canonical history, you need to view the history from the remote
> > > > +as `ours` (i.e. "our shared canonical history"), while what you did
> > > > +on your side branch as `theirs` (i.e. "one contributor's work on top
> > > > +of it").
> > >
> > > Total aside because I'm not sure what you could change here, but man
> > > do I hate this.
> > Uh it's actually documented? I'm always confused by this too. --ours
> > and --theirs at this point are pretty much tied to stage 2 and 3.
> > Nothing I can do about it. But if you could come up with some other
> > option names, then we could make "new ours" to be stage 3 during
> > rebase, for example.
> I don't think it's a naming issue, personally. Years ago we could
> have defined --ours and --theirs differently based on which kind of
> operation we were in the middle of, but you are probably right that
> they are now tied to stage 2 and 3. But there's another place that we
> might still be able to address this; I think the brain-damage here may
> have just been due to the fact that the recursive merge machinery was
> rather inflexible and required HEAD to be stage 2. If it were a
> little more flexible, then we might just be able to make this problem
> go away. Maybe it can still be fixed (I haven't dug too deeply into
> it), but if so, the only fix needed here would be to remove this long
> explanation about why the tool gets things totally backward.
Aha. I' not really deep in this merge business to know if stages 2 and
3 can be swapped. This is right up your alley. I'll just leave it to
> > > > +'git switch-branch' -c|-C <new_branch> [<start_point>]::
> > > > +
> > > > + Specifying `-c` causes a new branch to be created as if
> > > > + linkgit:git-branch were called and then switched to. In
> > > > + this case you can use the `--track` or `--no-track` options,
> > > > + which will be passed to 'git branch'. As a convenience,
> > > > + `--track` without `-c` implies branch creation; see the
> > > > + description of `--track` below.
> > >
> > > Can we get rid of --track/--no-track and just provide a flag (which
> > > takes no arguments) for the user to use? Problems with --track:
> > > * it's not even in your synopsis
> > > * user has to repeat themselves (e.g. 'next' in two places from '-c
> > > next --track origin/next'); this repetition is BOTH laborious AND
> > > error-prone
> > > * it's rather inconsistent: --track is the default due to
> > > auto-vivify when the user specifies nothing but a branch name that
> > > doesn't exist yet, but when the user realizes the branch doesn't exist
> > > yet and asks to have it created then suddenly tracking is not the
> > > default??
> > I don't think --track is default anymore (maybe I haven't updated the
> > man page correctly). The dwim behavior is only activated in
> > switch-branch when you specify --guess to reduce the amount of magic
> > we throw at the user. With that in mind, do we still hide
> > --track/--no-track from switch-branch?
> Ooh, you're adding --guess? Cool, that addresses my concerns, just in
> a different manner.
No it's always there even in git-checkout, just hidden.
> Personally, I'd leave --track/--no-track out. It's extra mental
> overhead, git branch has options for setting those if they need some
> special non-default setup, and if there is enough demand for it we can
> add it later. Removing options once published is much harder.
Slightly less convenient (you would need a combination of git-branch
and git-switch-branch, if you avoid git-checkout). But since I don't
think I have ever used this option, I'm fine with leaving it out and
considering adding it back later.
> > > I'm not sure what's best, but here's some food for thought:
> > >
> > >
> > > git switch-branch <branch>
> > > switches to <branch>, if it exists. Error cases:
> > > * If <branch> isn't actually a branch but a <tag> or
> > > <remote-tracking-branch> or <revision>, error out and suggest using
> > > --detach.
> > > * If <branch> isn't actually a branch but there is a similarly named
> > > <remote-tracking-branch> (e.g. origin/<branch>), then suggest using
> > > -c.
> > I would make these advice so I can hide them. Or if I manage to make
> > all these hints one line then I'll make it unconditional.
> > > git switch-branch -c <branch>
> > > creates <branch> and, if a relevant-remote-tracking branch exists,
> > > base the branch on that revision and set the new branch up to track
> > Hmm.. this is a bit magical and could be surprising. If I create (and
> > switch to) a new branch foo, I don't necessarily mean tracking
> > origin/foo (I may not even think about origin/foo when I type the
> > command). So tentatively no.
> Yeah, if you're adding --guess then I'm happy. I do think, though,
> that if the user runs switch-branch to a branch that doesn't exist, we
> should check if there is an associated remote-tracking branch so that
> we can provide a better error message and help users learn about
> --guess. (Also, will there be a short -g form?)
Yeah better error and suggestion is a good idea. And yes the short
form -g is already added (I did try to use it and find --guess too
time consuming even with bash completion support).
> > > > +-f::
> > > > +--force::
> > > > + Proceed even if the index or the working tree differs from
> > > > + HEAD. This is used to throw away local changes.
> > >
> > > Haven't thought through this thoroughly, but do we really need an
> > > option for that instead of telling users to 'git reset --hard HEAD'
> > > before switching branches if they want their stuff thrown away?
> > For me it's just a bit more convenient. Hit an error when switching
> > branch? Recall the command from bash history, stick -f in it and run.
> > Elsewhere I think both Junio and Thomas (or maybe only Junio) suggests
> > moving the "git reset" functionality without moving HEAD to one of
> > these commands, which goes the opposite direction...
> Fair enough.
I'm actually still not sure how to move it here (I guess 'here' is
restore-files since we won't move HEAD). All the --mixed, --merge and
--hard are confusing. But maybe we could just make 'git restore-files
--from HEAD -f :/" behave just like "git reset --hard HEAD" (but with
some safety net) But we can leave it for discussion in the next round.
> > > > +--orphan <new_branch>::
> > > > + Create a new 'orphan' branch, named <new_branch>, started from
> > > > + <start_point> and switch to it. The first commit made on this
> > >
> > > What?? started from <start_point>? The whole point of --orphan is
> > > you have no parent, i.e. no start point. Also, why does the
> > > explanation reference an argument that wasn't in the immediately
> > > preceding synopsis?
> > I guess bad phrasing. It should be "switch to <start_point> first,
> > then prepare the worktree so that the first commit will have no
> > parent". Or something along that line.
> > You should really review git-checkout.txt btw ;-)
> I did after writing several of these comments, and yeah, it really
> needs a clean up. Seems like something someone would do when writing
> a (partial) replacement or simplified alternative. ;-)
Heh ;-) Fine I'll do it. I have to read and re-read git-checkout.txt
anyway and already queued up a couple small fixes.
> > > > + 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 index and the working tree are adjusted as if you had previously run
> > > > +"git checkout <start_point>". This allows you to start a new history
> > > > +that records a set of paths similar to <start_point> by easily running
> > > > +"git commit -a" to make the root commit.
> > > > ++
> > > > +This can be useful when you want to publish the tree from a commit
> > > > +without exposing its full history. You might want to do this to publish
> > > > +an open source branch of a project whose current tree is "clean", but
> > > > +whose full history contains proprietary or otherwise encumbered bits of
> > > > +code.
> > > > ++
> > > > +If you want to start a disconnected history that records a set of paths
> > > > +that is totally different from the one of <start_point>, then you should
> > > > +clear the index and the working tree right after creating the orphan
> > > > +branch by running "git rm -rf ." from the top level of the working tree.
> > > > +Afterwards you will be ready to prepare your new files, repopulating the
> > > > +working tree, by copying them from elsewhere, extracting a tarball, etc.
> > >
> > > Ick. Seems overly complex. I'd rather that --orphan defaulted to
> > > clearing the index and working tree, and that one would need to pass
> > > HEAD for <start_point> if you wanted to start out with all those other
> > > files. That would certainly make the explanation a little clearer to
> > > users, and more natural when they start experimenting with it.
> > >
> > > However, --orphan is pretty special case. Do we perhaps want to leave
> > > it out of this new command and only include it in checkout?
> > I started this by simply splitting git-checkout in two commands that,
> > combined, can do everything git-checkout can. Then suggestions to have
> > better default came in and I think we started to drift further to
> > _removing_ options and falling back to git-checkout.
> > I think we could still keep "complicated" options as long as they are
> > clearly described and don't surprise users until they figure them out.
> > That way I don't have to go back to git-checkout and deal with all the
> > ambiguation it creates.
> Fair enough...though I think it may make sense to also review the
> complicated options and determine if they are overly complicated. I
> think --orphan qualifies (I stumbled with it a bit for years the
> occasional time I needed to use it), and my small suggestion above
> would simplify both it and its description. We should probably also
> consider just removing <start_point> as an acceptable argument to
> --orphan; if people want files from some revision after creating an
> orphan branch that's a simple extra command.
It is good that you pointed it out though. I still have to digest this
option before I make more comments, but generally if there's a simpler
(even if new) way to achieve the same thing, I'm all for it.
next prev parent reply other threads:[~2018-12-04 18:18 UTC|newest]
Thread overview: 110+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-11-10 13:35 [PATCH/RFC] checkout: print something when checking out paths Nguyễn Thái Ngọc Duy
2018-11-12 6:21 ` Junio C Hamano
2018-11-12 16:27 ` Duy Nguyen
2018-11-12 20:15 ` Junio C Hamano
2018-11-19 13:08 ` Ævar Arnfjörð Bjarmason
2018-11-19 15:19 ` Duy Nguyen
2018-11-20 2:53 ` Junio C Hamano
2018-11-20 17:45 ` [RFC] Introduce two new commands, switch-branch and restore-paths Duy Nguyen
2018-11-25 22:20 ` Thomas Gummerer
2018-11-26 3:03 ` Junio C Hamano
2018-11-26 15:37 ` Duy Nguyen
2018-11-26 16:00 ` Ævar Arnfjörð Bjarmason
2018-11-26 16:08 ` Duy Nguyen
2018-11-26 23:10 ` Stefan Beller
2018-11-27 0:34 ` Junio C Hamano
2018-11-27 16:52 ` [PATCH/RFC v2 0/7] Introduce new commands switch-branch and checkout-files Nguyễn Thái Ngọc Duy
2018-11-27 16:52 ` [PATCH v2 1/7] parse-options: allow parse_options_concat(NULL, options) Nguyễn Thái Ngọc Duy
2018-11-27 19:43 ` Stefan Beller
2018-11-28 15:22 ` Duy Nguyen
2018-11-28 4:47 ` Junio C Hamano
2018-11-27 16:52 ` [PATCH v2 2/7] checkout: make "opts" in cmd_checkout() a pointer Nguyễn Thái Ngọc Duy
2018-11-27 16:52 ` [PATCH v2 3/7] checkout: move 'confict_style' to checkout_opts Nguyễn Thái Ngọc Duy
2018-11-27 19:50 ` Stefan Beller
2018-11-27 16:52 ` [PATCH v2 4/7] checkout: move dwim_new_local_branch " Nguyễn Thái Ngọc Duy
2018-11-27 19:52 ` Stefan Beller
2018-11-27 16:52 ` [PATCH v2 5/7] checkout: split options array in three pieces Nguyễn Thái Ngọc Duy
2018-11-29 6:29 ` Junio C Hamano
2018-11-27 16:52 ` [PATCH v2 6/7] checkout: split into switch-branch and checkout-files Nguyễn Thái Ngọc Duy
2018-11-28 6:03 ` Junio C Hamano
2018-11-28 15:30 ` Duy Nguyen
2018-11-28 19:08 ` Stefan Beller
2018-11-28 19:18 ` Duy Nguyen
2018-11-29 5:55 ` Junio C Hamano
2018-11-28 23:22 ` Stefan Xenos
2018-11-28 23:26 ` Stefan Xenos
2018-11-28 23:37 ` Stefan Xenos
2018-11-29 5:59 ` Junio C Hamano
2018-11-29 15:36 ` Duy Nguyen
2018-11-29 15:46 ` Duy Nguyen
2018-11-29 18:14 ` Stefan Beller
2018-11-29 18:30 ` Duy Nguyen
2018-11-29 19:29 ` Stefan Xenos
2018-11-27 16:52 ` [PATCH v2 7/7] Suggest other commands instead of "git checkout" Nguyễn Thái Ngọc Duy
2018-11-28 6:04 ` Junio C Hamano
2018-11-28 15:33 ` Duy Nguyen
2018-11-29 6:05 ` Junio C Hamano
2018-11-28 20:01 ` [PATCH/RFC v2 0/7] Introduce new commands switch-branch and checkout-files Duy Nguyen
2018-11-28 20:09 ` Duy Nguyen
2018-11-28 20:30 ` Stefan Beller
2018-11-29 15:33 ` Duy Nguyen
2018-12-03 21:42 ` Stefan Beller
2018-11-30 1:47 ` Junio C Hamano
[not found] ` <CAPL8Ziuj7Ffmdvz6NZWSJ+vzAtxFQhO1cfY2wmXm16J_8sY5fw@mail.gmail.com>
2018-11-28 22:53 ` Stefan Xenos
2018-11-29 6:14 ` Junio C Hamano
2018-11-29 21:58 ` [PATCH/RFC v3 00/14] Introduce new commands switch-branch and restore-files Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 01/14] git-checkout.txt: fix one syntax line Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 02/14] git-checkout.txt: split detached head section out Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 03/14] checkout: factor out some code in parse_branchname_arg() Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 04/14] checkout: make "opts" in cmd_checkout() a pointer Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 05/14] checkout: move 'confict_style' and 'dwim_..' to checkout_opts Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 06/14] checkout: split options array in three pieces Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 07/14] checkout: split into switch-branch and restore-files Nguyễn Thái Ngọc Duy
2018-12-04 0:45 ` Elijah Newren
2018-12-04 3:33 ` Junio C Hamano
2018-12-04 16:21 ` Duy Nguyen
2018-12-04 17:43 ` Elijah Newren
2018-12-04 18:17 ` Duy Nguyen [this message]
2018-12-05 2:25 ` Junio C Hamano
2018-12-05 4:45 ` Elijah Newren
2018-12-05 6:56 ` Junio C Hamano
2018-12-05 2:14 ` Junio C Hamano
2018-12-05 4:22 ` Elijah Newren
2018-11-29 21:58 ` [PATCH v3 08/14] switch-branch: better names for -b and -B Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 09/14] switch-branch: stop accepting pathspec Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 10/14] switch-branch: reject "do nothing" case Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 11/14] switch-branch: only allow explicit detached HEAD Nguyễn Thái Ngọc Duy
2019-03-10 19:32 ` Eckhard Maaß
2019-03-11 14:27 ` Duy Nguyen
2018-11-29 21:58 ` [PATCH v3 12/14] restore-files: take tree-ish from --from option instead Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 13/14] restore-files: make pathspec mandatory Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 14/14] doc: promote "git switch-branch" and "git restore-files" Nguyễn Thái Ngọc Duy
2018-11-29 23:05 ` [PATCH/RFC v3 00/14] Introduce new commands switch-branch and restore-files Ævar Arnfjörð Bjarmason
2018-11-29 23:18 ` Ævar Arnfjörð Bjarmason
2018-11-29 23:37 ` Dan Fabulich
2018-11-30 0:16 ` Dan Fabulich
2018-11-30 6:49 ` Duy Nguyen
2018-11-30 5:37 ` Duy Nguyen
2018-11-30 6:47 ` Junio C Hamano
2018-11-30 11:29 ` Ævar Arnfjörð Bjarmason
2018-11-30 12:10 ` Duy Nguyen
2018-11-30 2:16 ` Junio C Hamano
2018-11-30 5:41 ` Duy Nguyen
2018-11-30 6:46 ` Junio C Hamano
2018-12-02 18:58 ` Thomas Gummerer
2018-12-02 19:46 ` Junio C Hamano
2018-12-04 1:28 ` Elijah Newren
2018-12-04 16:27 ` Duy Nguyen
2018-12-04 17:45 ` Elijah Newren
2018-12-04 18:22 ` Duy Nguyen
2018-12-04 18:31 ` Elijah Newren
2018-12-04 18:39 ` Duy Nguyen
2018-12-04 21:18 ` Eric Sunshine
2018-11-13 18:28 ` [PATCH v2] checkout: print something when checking out paths Nguyễn Thái Ngọc Duy
2018-11-14 10:12 ` Junio C Hamano
2018-11-14 15:31 ` Duy Nguyen
2019-01-28 21:58 ` Junio C Hamano
2019-01-29 1:26 ` Duy Nguyen
2019-02-06 2:51 ` [PATCH 0/2] nd/checkout-noisy updates Nguyễn Thái Ngọc Duy
2019-02-06 2:51 ` [PATCH 1/2] checkout: update count-checkouts messages Nguyễn Thái Ngọc Duy
2019-02-06 2:51 ` [PATCH 2/2] checkout: count and print -m paths separately Nguyễn Thái Ngọc Duy
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:
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
* 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.
Code repositories for project(s) associated with this public inbox
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).