Re: [PATCH] Documentation: add a planning document for the next CLI revamp

On Wed, Oct 29, 2008 at 05:22:00PM -0700, Sam Vilain wrote:

Thanks for putting this together.

These seem reasonable.

I notice the commit template message getting longer and longer. Maybe it is time for status.verbosetemplate (which could default to true, I just want to be able to turn it off).

There is already infrastructure that figures out exactly what the situation is (no changes versus changes in untracked files versus changes in unstaged files), so it should just be a matter of tweaking the messages.

Definitely.

I think I would make it "-R, --reverse", since it really is analagous to "git diff -R".

This is an awful name, IMHO. It doesn't point out _what_ you're undoing, so it leaves me with the feeling that you can undo arbitrary things. I think the name needs to be considered along with related operations.

So think of us as having three "spots": the HEAD (H), the "stage"[1] (S), and the working tree (W). And we want commands for moving content between them. Now we have:

  W->S: add
  H->S: reset --
  S->W: checkout --
  S->H: commit (no paths)

And if you want to include things that jump the staging area:

  W->H: commit (paths or -a)
  H->W: checkout HEAD --

So I think with your stage/unstage, we have:

  W->S: stage
  H->S: unstage
  S->W: ?
  S->H: commit (no paths)
  W->H: commit (paths or -a)
  H->W: ?

So I think we can note something: movement commands are related based on their _destination_. So since both of the missing ones impact the working tree, they should have a related name.

But do note the difference between "stage vs unstage" as opposed to "commit versus commit -a". I think this is because the stage sits in the middle. So it is mentally "which direction are changes coming from" and not "how _far_ are changes coming from".

So by that rationale, we should have a single command which says "put stuff in the working tree", with a flag for "from HEAD" versus "from the staging area." And that's what we have right now with "git checkout". The real problem with it is that it is an overload of checkout's other behavior of switching branches.

So what I am saying is "git undo" _must_ support both "put index content into working tree" as well as "put HEAD content into working tree", or it will be a step backwards in consistency.

So I guess that doesn't really suggest a name. But "undo" is awful. ;P

Side note: there are actually _other_ places you might want to move content. Like a stash. So now you can think of it as:

                 stash
                  ^  ^
                 /    \
                /      \
               v        v
  HEAD <--> stage <--> working tree

So maybe we just need a "git content" command. And then you can "git content --from=HEAD --to=tree <paths>" or "git content --from=tree --to=stash", with all equally supporting "--interactive". And of course I am kidding, because typing that would be awful. But I think conceptually, it makes sense. To me, anyway.

Blech. I think switching branches is the one thing that checkout does unconfusedly. And this is much more typing. Not to mention that So I would rather see "git switch" if checkout is somehow unpalatable.

But I don't know that it is. This seems like an attempt to say "branch operations should all be part of 'git branch'". But checkout isn't necessarily a branch operation. Consider detaching HEAD to a tag. Should it be "git tag --switch"?

I think this is reasonable even without other changes, just to override any configuration.

There was a thread between me and Junio some months ago that touched on this. I don't remember all of the arguments, but it was resolved to keep the current behavior. Any proposal along these lines should at least revisit and respond to those arguments.

I have this patch done and sitting in my repo, but I need to add the "without special configuration" bit and add tests and docs.

This should at least be configurable (even if it defaults to "on"). "-v" is more expensive, and not always wanted.

I, for one, just use "git branch" to get the current branch. I don't know of a more obvious way to ask for it (and please don't mention an ever-changing bash prompt).

I remember somebody talking about this, but not the details. Which information?

I would prefer that personally. I think Linus has been very reasonable in the past about recognizing that his workflow and speed requirements aren't always typical, and being willing to accept setting a configuration flag in those cases. So I think if he ack'd such a patch, nobody else would complain.

I agree, if you mean "does what ... does now" means "looks to the user like ... is happening". This is much more sanely done using git-checkout-index (though somebody suggested "remote export", which would need to use tar itself).

But not all of those things are necessarily related, and some of them have security implications. I would hate to get a bug report like "I used --server because I wanted to share my content via dumb http, but my repo was p0wned because of too-loose group permissions."

-Peff