[FAQ?] Rationale for git's way to manage the index

Hi,

I've read the manual, and I belive I have a correct understanding of how the index works, technically speaking. Still, I'm not clear about the rational for such design.

Almost any other decent system has an equivalent to cache the stat information (bzr calls this stat-cache, hg calls it dirstate IIRC). That is, if your run "$vcs diff" twice, the second run will only need to stat all files, never diff them.

But the fact that git actually remembers the _content_ of files in the index, and that the default behavior for "commit" is to commit only the content that is explicitely "git add"ed is something I've never seen outside git.

At first, I find it rather annoying. My usual workflow is

<hack hack hack> % $vcs status % $vcs commit -m "describe whatever I did" <hack hack hack> ...

With git, i'd do

<hack hack hack> % git status % git add X % git add Y % git status % git commit

or

<hack hack hack> % git satus -a % git commit -a -m "..."

In the former case, I have more commands to type, and in the second case, I loose part of the stat-cache benefit: If I run "git status -a" twice, the second run will actually diff all the files touched since the last run, since "git status -a" actually updated a temporary index, and discarded it afterwards, so it doesn't update the stat information in the index (while "git status" would have).

In both cases, I can't really see the benefit. I'm pretty sure this is a FAQ, and I'm also pretty sure there are good arguments for it, but I can't find it anywhere.

Thanks for your answers,

Hi,

On Sun, 6 May 2007, Matthieu Moy wrote:

Have you tried "git status" _without "-a"?

The benefit is a clear distinguishing between DWIM and low level. The index contains _exactly_ what you told it to contain. By forcing users to use "-a" with "git commit", you make it clear that a separate update steo is involved, and if you made an error (which you see from the file list), you can abort, and start over with the original index.

Hth, Dscho

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

Reading my message (including the last 5 words of the sentence you're quoting) would have told you that ;-).

In other systems, commit commits _exactly_ the content of files on disk. And most people seem happy with that.

Does this mean that the normal way to use "commit" is to use "-a"?

Well, with those kind of arguments, I could have my web browser not do DNS resolution for me, because it would make it clear that a separate step from HTTP request is involved. Still, this low-level thing brings no benefit to the user, and I know no web browser forcing the user to make this distinction.

You don't necessarily see your error from the file list:

% vi foo.c
% git add foo.c
% vi foo.c
% git commit -m foo
[...]
 create mode 100644 foo.c
%

This commited the old content of foo.c, while I hardly see any scenario where this is the expected behavior.

Then, being able to repare the error if I made it is interesting, but I don't get the reason why the error could not just be avoided.

Well, indeed, I just found a thread talking about this:

  http://lists-archives.org/git/196050-making-git-commit-to-mean-git-commit-a.html

I'll go through it, I might understand better after that ;-).

Thanks,

Matthieu Moy <Matthieu.Moy@imag.fr> writes:

One reason why is because you are using "-m foo" (a very non-descriptive commit message that would not help anybody including yourself in the future). Try the above without giving such a bogus error message with "-m" to commit, but instead let it spawn your editor --- you would be doing that in real-life when you are doing anything nontrivial. Then notice what appears on the file list of "Changed but not updated" section.

A single liner "-m" is handy for "Oops, typofix in foo.c" kind of commit, but in such a case you literally would be changing only the typofix and won't have "edit foo.c; git add foo.c; edit foo.c; git commit" sequence anyway.

I think Linus explained quite well to correct your doubts in your original message, and I do not have anything to add.

On Sun, May 06, 2007 at 07:43:31PM CEST, Junio C Hamano wrote:

I don't get this argument - I frequently write quite long descriptions inside the -m argument(s), since I just find it more convenient than having to edit it in an editor, for various reasons. So there is really no reason why the "-m is only for short single-liner commit messages" hypothesis could hold true.

Hi,

On Wed, 9 May 2007, Petr Baudis wrote:

:-) You yourself provided a reason in another reply: typos.

Another reason is that you can see how the end result will look like in an editor. For example, you'll have a hard time making sure in the command line that the lines are no longer than 76 characters.

Ciao, Dscho

  Hi,

On Wed, May 09, 2007 at 03:57:28PM CEST, Johannes Schindelin wrote:

  oh, indeed - good point. cg-commit uses fmt to format the message, I
think git-commit should do the same; let's see how controversial such a
change would be.

--- This makes git-commit filter log messages provided on commandline by fmt, thus making nice paragraphs from them. This makes it possible to specify even long commit messages on command line without worrying about this, akin to cg-commit.

Signed-off-by: Petr Baudis <pasky@suse.cz>
---

 git-commit.sh |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

Petr Baudis <pasky@suse.cz> writes:

I wouldn't do that for the first line of the message.

Someone typing

$ git commit -m "a very very very very very very very very very very very very long summary" \
             -m "a longer description of the above summary"

Probably doesn't want his first line to be broken (otherwise, git-format-patch and other tools would be confused).

So, that would be more like

echo "$log_message" | (read first_line; echo "$first_line"; fmt)

Perhaps another option would be to provide, say, a -M option, doing

log_message="$log_message

$(echo $1 | fmt)"

to allow people to explicitely say whether they want reformatting. But that's probably overkill.

On Wed, May 09, 2007 at 04:59:03PM CEST, Matthieu Moy wrote:

Hmm, I don't really know if it's more evil to split an extra-long line to two or keep it longer than the maximum sane width. Since I'm torn, I'd prefer to go for the version that's simpler (also, avoids weird results for those who for some reason chose not to follow the usual convention, but that's a minor point).

I don't really care, but if noone else does either, I'd stay with the current simple version. :)

Petr Baudis <pasky@suse.cz> writes:

The evil already happened several times in git's repository ;-).

$ git log --all --pretty=oneline | grep \
 ' ................................................................................' \
 | wc -l
81
$

When I encounter such long line, I often just don't care, since my terminal or tool (gitk ...) is often more than 80 char. And in the cases I care, the fix is just to enlarge the window or to scroll (only people using a text-mode console would _really_ be disturbed).

With the other solution (breaking the line automatically), I have no
easy fix. In gitk, I have the beginning of a sentence in the summary
field, in a mailed patched, I have the sentence split between the
Subject: header and the body.

(but we agree that both cases are evil. Perhaps just "ERROR: you're doing evil" would be better ...)

Hi,

On Wed, 9 May 2007, Petr Baudis wrote:

FWIW, I have a builtin git-fmt in my local repo, which uses the (slightly enhanced) functions in utf8.c... Maybe after 1.5.2 I dare to submit this...

Ciao, Dscho

Petr Baudis <pasky@suse.cz> writes:

Two points.

 * You would not want to wrap the first line;

 * 75-column is not ideal for every project, so this needs to be
   customizable;

 * If we were to munge the given message, we would probably also
   want to enforce "single-liner summary, empty line, and then
   the rest" convention.

Well, I have three there, but I suspect the first two somebody else may have said already, so...

This is slightly related, but I have been wondering about the interaction with "single-liner summary, empty line and then the rest" convention and various commands in the log family.

Currently, --pretty=oneline and --pretty=email (hence format-patch) take and use only the first line. I think we could change it to:

 - take the first paragraph, where the definition of the first
   paragraph is "skip all blank lines from the beginning, and
   then grab everything up to the next empty line".

 - replace all line breaks with a whitespace.

This change would not affect well-behaved commit messages that adhere to the convention, as their first paragraph always consist of a single line. On the other hand, people from different culture can get frustrated by their commit message chomped at the first linebreak in the middle of sentence right now, which would be helped by this change.

Their Subject: and --pretty=oneline output would become very long and unsightly, but their commit messages are already ugly anyway, and such a change at least avoid the loss of information.

If we were to do this, Subject: line would most likely use RFC2822 line folding at the places where line breaks were in the original, but that goes without saying.

What do people think?

Junio C Hamano wrote:

[...]

I agree that it is a good idea. This would e.g. help projects which are imported from other SCM, which does not have "single-liner summary, empty line and then the rest" convention of formatting commit messages.

BTW. does rebase work correctly for commits which do not use above convention?

You might find it useful to break your question into 2 pieces.

One is what information should be in the index, which essentially is what Linus addresses. The way I look at this, at the moment, is that the index contains whatever's required to make git-write-tree work without collecting information elsewhere. I suspect this is the correct historical way to look at this, but I wasn't on this list then.

The other is how to get information into the index. I think this is the original thing that seemed strange to you? It did to me. But, in part, since git has both "git-commit" and "git-commit -a", this is somewhat recognized. I've wondered if there's a way to improve this, but I don't have any coherent ideas right now. Thanks for finding and posting that thread; that was helpful.

Also, the idea of an index isn't all that strange. I need to use perforce at work, and it has an index (called "db.have"). But it is stored on the server and has everyone's state mixed together, uses the type of file IDs Linus complains about, and is more difficult to manipulate (hence less useful). Being on the server is a great performance bottleneck as well.

Dana

On 5/6/07, Matthieu Moy <Matthieu.Moy@imag.fr> wrote:

Hi Matthieu,

On Sun, 6 May 2007, Matthieu Moy wrote:

Okay, I rephrase the (badly worded) question:

Why did you use "-a" with "git status" to begin with? It's useless.

Because they do not realize that the file _names_ are actually only a key, not the value.

With Git, it is possible to stage changes, but also to have a dirty stage.

Think, for example, about debugging a program. Many programs have Makefiles, which define CFLAGS without "-g". Now you want to debug. Since gdb acquired the bad habit of not working properly at all without that flag (which is especially apparent when single stepping jumps around wildly in the source code), you _have_ to change the Makefile to include "-g" with the CFLAGS.

But you don't want to commit _that_. It is no useful change for the project. Submitting such a patch makes you look foolish. So, you leave it out of the commit.

And to make you _aware_ that it is a real possibility, and often a desirable one, git-commit makes you specify "-a" when you are _sure_ that you want to commit _all_ of your changes to the tracked files.

With CVS (which has been bashed on a lot on this list, and rightfully so), after a mistaken "cvs commit" _with_ irrelevant changes, like the change to the Makefile I illustrated above), you have two options:

	- leave it as it is (possibly undoing the change in a subsequent 
	  commit), or

	- edit the files, which often leads to an inconsistent repository. 
	  Yeah, sure, you can checkout the newest state, but you cannot 
	  reproduce known older states.

Well, I use it quite a lot. But 30% of the time, I prefer to commit with specific filenames, so I can be sure _what_ I commit. FWIW, I picked up on that practice when using CVS...

There are even about 20% of the time, when I use "git commit" _without_ any parameters, because I used "git add" to tell Git that I resolved some conflicts, or that I want this file to be committed, while other files should not be committed.

No. _You_ never need to tell the browser _not_ to resolve via DNS.

But _you_ sometimes _need_ to commit with _different_ parameters than "-a". You might not realize that _now_. But at least specifying "-a" everytime you do your thing gives you a _chance_ to realize it.

As others have commented, "-m" is a _bad_ option. Yes, for ease of use, it is provided.

But how useful is a commit message which consists of less than five words?

It does _not_ tell you,

	- what the _conceptual_ change was,
	- _why_ it was done,
	- _how_ it was done, and
	- what the rationale of the committer was, for the case that 
	  people try to come up with a cleverer patch, to prevent 
	  unnecessary rethinking.

Ciao, Dscho

On Sun, 6 May 2007, Matthieu Moy wrote:

Yeah. You'd better get used to it, because it's fundamental.

Here's the rationale list:

 - It's fundamentally the only sane thing to do.

   Git tracks content at _all_ levels, not "files". So this is more than 
   an implementation issue, it's a fundamental "how the world works" 
   issue. The fact that everybody else gets it wrong is _their_ problem. 

   [ Corollary: the fact that your brain has rotted from using those 
     broken systems is obviously your problem, and sadly, there's nothing 
     else we can do than try to show the right way and hope that the 
     neurons re-generate. CVS has caused endless suffering, this is just 
     one small example of it ]

 - You fundamentally cannot do it any other way. 

   Not doing it the way git does it (point to the content) means that the 
   index-replacement has to point to something else, namely a "file ID". 

   That's so broken as to be really really sad. In CVS, for example, there 
   obviously isn't any "file ID", so what does the "index" in CVS point 
   at? 

   Right. The "index" in CVS is the Entries file, and it not only lacks 
   stat information, it also lacks any other information, which means that 
   the "file ID" is _literally_ just the pathname itself. That causes 
   obvious problems, so nobody sane would ever suggest that this is a good 
   idea.

   So what do other people use? They tend to not have understood the 
   "content is king" thing (which is what git uses), so they add somethng 
   *else* to the "index" file than the content. What can I say? People are 
   morons. I'm constantly amazed at just how stupid SCM people seem to be.

   In most systems, that "something else" is a "file ID". That just means 
   that they are fundamentally broken whenever they do any trivial merge 
   with renames. Just don't do it. I've talked before about why tracking 
   file ID's is wrong - it's just as wrong as thinking that the "ID" of a 
   file is the path. 

 - Tracking content in the index is fundamentally how and why git can do 
   merges so much better than anything else, and how we handle conflicts 
   gracefully.

   Trust me, you haven't seen good merge conflict support until you've 
   done a git merge, and realized that you can do things like just

	git diff

   to see just the *conflicting* parts, not the stuff you don't need to 
   worry about. And it's why you can do

	git diff --base/--ours/--theirs

   to see what the diffs of the conflicting files are wrt the versions 
   that got us there. Again, a big part of this is that the index tracks 
   *content* rather than some totally idiotic secondary notion that has 
   nothing to do with anything sane.

That's the three major reasons. The first one may not seem relevant to you, but when you start to understand that "content is the only thing that matters", you'll move to a whole new level. Not just in git, but in general. So the first argument is purely philosophical, but it's still important.

The two other rationales are purely practical. It's why git is simply _better_ than the alternatives. It's why git can do things that others cannot do, or that they have to do strange and weird things for, and git does totally naturally without having to even think about it.

A file-ID-based thing will always have fundamental problems with file ID clashes - issues that cause annoyances both small and big. Git just doesn't have that fundamental design bug.

You'll just need to get used to it. The git way is actually much better. You'll get used to it quickly enough, but once you do, what's the problem with the workflow you already quote:

What's so hard with adding that "-a" to "git commit"? You don't even need it on the status line, the status is relevant and understandable (and actually tells you more) even without it.

WHY do you care?

Git is still about an order of magnitude faster than anything that you can compare with, so I really don't see what you're complaining about?

You seem to be complaining about the fact that:

 - git does extra and unnecessary work when you give it an extra and 
   unnecessary flag (the "-a" to "git status".

 - despite the fact that you can make git do unnecessary things, I can 
   pretty much guarantee that your workflow is still faster with git than 
   with pretty much anything else, so why complain?

So both of your complaints seem to be a bit pointless to me. But the real answer really is:

 - git does things better, and the git approach actually allows you a 
   better workflow. Now, admittedly that better workflow is especially 
   notable when you have a merge conflict or other nastier situation and 
   not as obvious when you just don't do anything exciting, but it's 
   actually also more *logical* even in the absense of any merge issues 
   (ie the whole "content vs filenames" issue).

 - but git doesn't *force* that better workflow, and you can always just 
   use "git commit -a" to emulate the stupidity that is CVS and SVN. 

Basically, I use the "git commit -a" for all the trivial cases, but equally often I carry around independent changes in my tree (often for long times - right now my tree has some experimental stuff I haven't committed yet in fs/ext3/ialloc.c for example) and I work with a dirty tree and commit and change _parts_ of it. And then the "-a" thing is wrong, and having it as the default would just cause mistakes.

So git really does the right thing, for so many reasons. But yeah, the right thing is different from what CVS does.

(That statement is so true that it basically could be used ass a definition of CVS: "tThe right thing is different from what CVS does" is not about the index, it's about almost _everything_)

		Linus

Linus Torvalds <torvalds@linux-foundation.org> writes:

Thanks a lot for the detailed explanations.

Note that I'm not "complaining", but just not understanding something.

(I would actually complain about the documentation not being clear enough, but I'll try to complain with a contribution instead ;-) I'll add something to the FAQ on the wiki, but it's down right now).

Well, git's index still tells more than "the content FOOBAR exists, somewhere". It also "contains", if not "points to", the file name.

Off course, I don't have strong argument against it. The biggest annoyance is that my fingers are used to "commit -m message", and now type "commit -a message", but ...

The reason why I'm posting this is that I was wondering whether "commit -a" not being the default was supposed to be a message like "you shouln't use it too often".

It seems it isn't. I'll just get used to "commit -a" (and probably alias it), and discover the actual benefits of the index little by little.

                                   ^^^
Not sure this was intentional, but your spelling of "as" when used to
talk about CVS seems to reveal something about your state of mind ;-).

Thanks,

On Sun, 6 May 2007, Matthieu Moy wrote:

Indeed. 

Git's index is basically very much defined as

 - sufficient to contain the total "content" of the tree (and this 
   includes all metadata: the filename, the mode, and the file contents 
   are all *parts* of the "content", and they are all meaningless on their 
   own!)

 - additional "stat" information to allow the obvious and trivial (but 
   hugely important!) filesystem comparison optimizations.

So you really should see it as *being* the content. The content is not the "file name" or the "file content" as separate parts. You really cannot separate the two. Filenames on their own make no sense (they have to have file content too), and file content on its own is similarly senseless (you have to know how to reach it).

What I'm trying to say is that git fundmaentally doesn't _allow_ you to see a filename without its content. The whole notion is insane and not valid. It has no relevance for "reality".

Also, you should realize that when you do

	git add X

you are *not* adding the filename X. No, "X" is literally a "content path pattern", the same way it is when you do something like

	gitk X

and it's worth always keeping in mind that in neither case is "X" necessarily a single file, but literally a pathname pattern that is used as a "filter" on all the possible patterns.

(Of course, the filtering rules are different for "git add" and "gitk": in the "git add" example, you filter the working tree files, while in "gitk" you filter the files that git already knows about, so they are different, but in both cases you really should think of them as filters, not as "filenames", even though one _trivial_ filter is to give a filter that matches exactly one pathname).

No, "git commit -a" is undoubtedly _convenient_. You can use it as often as you like.

So as long as you see it as a convenience feature, and realize that "git commit" is actually a lot more powerful than just being able to always do the convenient, go on and use "git commit -a" all the time.

When you hit a situation where you want to do something slightly subtler, you'll suddenly be really happy that you always had the convenience feature, but that git didn't make you think that it was how you _had_ to work.

Indeed ;)

Freudian slip. But yes, I'm really down on CVS. The only thing I like less than CVS is SVN, and that's just because I think it's such a sad waste, not because it's actually _worse_ than CVS. (Ie I dislike SVN from a "it could have been so much better" perspective).

			Linus

On Sun, 6 May 2007, Matthieu Moy wrote:

Well, personally I practically never use it, I find that having a separation between what the current state of my tree is and what will be comitted to be one of the really "oh wow, why doens't everything else do this?" features. However, i tend to be working on more than one thing at once, and switch between them - so I commit work on A while work on B is still unfinished, then start C, finish B some point later and commit it, and then I can finish C. Git is the first VCS that supports a butterfly mind :P.

"git add -i" - this is a feature I have wanted since I started using version control ...

On 2007-05-06 23:53:13 +0100, Julian Phillips wrote:

git-gui is really handy for adding/committing a subset of the changes in your working tree. Especially for those of us with goldfish memory, since it's so easy to see exactly what's happening: what's going to be committed and what not.

I thought "git add -i" was the best thing since sliced bread -- until I found the same feature in git-gui, but with a _much_ better interface. Just right-click on a hunk in a diff, and you have the option of staging/unstaging that hunk. Pure magic.

Karl Hasselstr??m <kha@treskal.com> wrote:

"git add -i" has a hunk splitting feature that git-gui lacks. I'm thinking of adding features to git-gui to let you select a region of a hunk using the text selection, and then stage only that selection. I also want to let you revert hunks from the working directory copy.

But after reading Junio's comments about "git add -i" being a possibly bad idea and instead letting you park everything into a shelf, reset --hard your working directory to HEAD and then pull things back off the shelf to be staged, I might want to do that differently in git-gui... like use a shelf. ;-)

But I'm glad someone else finds the hunk feature useful in git-gui. I use it far too often myself.

"Shawn O. Pearce" wrote:

It it among the most-wanted features here. We discovered it only because Karl mentioned it yesterday. ;)

-- Hannes

On 2007-05-08 09:15:45 +0200, Johannes Sixt wrote:

See? Who said spamming doesn't work? :-)

I think it would be worth introducing git-gui as a commit tool in the tutorial(s) and the manual. It gives a very nice graphical representation of the dirty state you're going to commit, and the dirty state you aren't going to commit because you haven't staged it yet. The only drawback is that it's a lot of work to make documentation with screenshots ...

On Tue, May 08, 2007 at 12:28:36PM +0200, Karl Hasselström wrote:

You could put that on a web page someplace.

For the tutorial and user manual, could git-gui be treated similar gitk, with just a one- or two- line mention here and there? I haven't used it, so don't know where it would most logically fit in....

--b.

On 2007-05-08 08:40:27 -0400, J. Bruce Fields wrote:

I would introduce it with a paragraph or two right where committing is covered the first time. Explain that the empty file list box to the left contains the changes that will be committed when you press the commit button, and that the file list box on the right contains the changes that won't be committed. By clicking on a file name you get to see the diff to the file, and by clicking on the icon you move it to the other file list box -- that is, you stage/unstage it.

And now comes the clever part: Introduce the index, by explaining that it essentially _is_ the left file list box. Explain that git-add is the command-line equivalent of moving changes to the left box, and that git-commit without arguments simply commits what's in the index -- exactly like git-gui's Commit button.

I think it could work. :-)

On Tue, May 08, 2007 at 04:53:11PM +0200, Karl Hasselström wrote:

Definitely, sounds fun.

For the in-tree documentation, maybe I'm just my crusty text-centric commandline point of view, but I'd rather have the primary explanation continue to depend only on text and commandline examples, and then add a note telling people that playing with git-gui may help develop their intuition for the way the index works.

But I think it'd be interesting to try out the above approach with screenshots, etc., on a web page someplace. It might also make a good visual aid for a talk.

--b.

Hi,

On Tue, 8 May 2007, J. Bruce Fields wrote:

Usually a wiki is a perfect place to start this...

Ciao, Dscho

On 2007-05-07 21:41:14 -0400, Shawn O. Pearce wrote:

That would be useful. It's currently possible to split some hunks by reducing the number of content lines, but if the changes aren't separated by any unchanged lines at all, that doesn't work.

That would be handy. But unlike stage/unstage, this can lose information, so there'd need to be some kind of "are you _really_ sure? [Yes] [No]" safety hatch, which would make it less convenient.

A shelf could be handy. Actually, it could be handy to have more than one. Then one could go through the mess in one's working directory and toss changes into one bin for each commit one plans to create -- including one "trash" bin for hunks one would like to revert.

I assume that shelves would be implemented as branches that are precisely one commit on top of HEAD? If so, I'd just like to point out that they're exactly like unapplied patches in StGIT.

Hmm. I find it inconsistent to force or strongly encourage the user to commit precisely the working directory changes and not a subset thereof, which the shelf idea seems to encourage, while at the same time not committing straight from the working directory but from a specific staging area (the index).

I don't think it's a bad thing. If I've made several unrelated changes and want to commit them separately for the sake of readable history, how exactly is that a bad thing when compared to committing it all at once? If I care about clean history in the first place, then presumably I'll test the commits in isolation if I deem it necessary -- and if I don't, then I probably won't test anyway even if the tool makes it easy.

Karl Hasselstr??m <kha@treskal.com> wrote:

Yea, I've played that game before too (reduce content lines) to try and simulate a hunk splitter. ;-) Doesn't always work.

Right now I feel like a huge chunk of the git-gui code is simply not maintainable. The 0.7.0 release is really more about refactoring the code to make it more maintainable, than it is about actual features (though there are some new things, like vi-keys).

The hunk selection stuff is just one part of the 2,000 lines still left in git-gui.sh itself, and that still uses a lot of messy globals. I want to get the code better organized before I take on major new additions to it.

True, but that beats the tar out of copying the - lines to your clipboard and pasting them into your text editor, then deleting the - prefix. Especially if its a couple of hunks that you want to revert. Which I find myself doing all to often.

Actually I work around it today by staging what I care about, then reverting the file. Since the revert comes out of the index, I get (mostly) the same action as reverting a particular hunk. But it does mean that I lose my index state, if that happened to be of any particular interest.

I haven't looked at StGIT in a while.  I've seen noise on the list
about nifty features being added, but I haven't kept up with what
those features actually are.  I think you are right about this and
maybe git-gui should try to be compatible with StGIT's unapplied
patches, should I get into actually implementing a shelving system.
 

Indeed; I was thinking that this very morning. Making an index that you stage things into, but then also saying you cannot really do that and instead have to shelve what you don't want - that's just evil. I'll have to think about it more.

The blame interface in git-gui needs help more than the index
staging features.  The colors suck.  ;-)
 

Hi,

On Sun, 6 May 2007, Matthieu Moy wrote:

As you pointed out yourself, the index _has_ an idea of the content of that file. So, arguably, it does not point to _that_ file, but rather to that file _with a certain content_.

Just another reason to hate CVS. Because it trained people to do that. If it was not for the training by CVS, I would have strongly opposed to the introduction of the "-m" switch to commit. It _encourages_ bad commit messages.

Now, with Git I usually let git-commit start up the editor. Because then I am actually encouraged to make up my mind, and put down a meaningful message, which might not only help _others_ to understand why I did it, and how, but also _myself_ (after a few months).

IMHO yes, that is the message.

In addition to being nice to people used to the behaviour of "git commit" _without_ other arguments.

Ciao, Dscho

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

Well, this really depends on the use-case, size of commit, ...

I often use a version control system for very low importance stuff. I don't want to type a 3-lines long message to describe a 2-lines long change in my ~/.emacs.el for example. I also work with people using (sorry) svn to work collaboratively, but they don't even provide a log message: the version control system here is just a replacement for unison/NFS/whatever other way to have people edit files from different machines.

For sure, in a context where code quality and review is important, -m "xxx" isn't the way (except if you prefer your shell's line editor to your actual editor).

Hi,

On Mon, 7 May 2007, Matthieu Moy wrote:

Okay, so I use "-m" myself sometimes.

IIRC our record is 90+ lines of commit message for a one-line change.

I positively _hate_ empty commit messages. There is _always_ something to be said about the intent of the change, that has no place in the code.

I also find it very useful for my own pleasure when reviewing some logs. I track config files, small scripts, documents, etc. with Git, and I found myself looking for something in _all_ of them. The commit messages helped.

Commit messages, BTW, are somewhat of an artform. You cannot imagine how slow I am writing them, because they should be helpful not only for the reviewer, but also for the casual git-blame user, who wants to find out the rationale of a change.

Ciao, Dscho

  Hi,

On Mon, May 07, 2007 at 01:05:44PM CEST, Johannes Schindelin wrote:

  I'm maybe somewhat standing out of the crowd, but I sometimes use -m
for *very* long commit messages - just using separate -m parameters for
paragraphs and writing on; I tend to find it much more natural than
spawning an editor. Only when I find later that I've made an ugly typo
in the middle of 250-characters commandline or I figure out that I
should add some figure to the message, I throw in -e at the end and add
the final touches.

..snip..

  But I agree that commit messages are somewhat of an artform, and
just finding a good headline can be quite difficult sometime. :-)

On 5/7/07, Matthieu Moy <Matthieu.Moy@imag.fr> wrote:

Heh. Making the index very visible makes sense when you are merging, Linus and Junio are both integrators and spend a lot of time merging. Hence the default is for git-commit to observe the index.

I agree with Linus' other points too, but at the end of the day, it makes life easier and saner mainly when merging, at the expense of having to pay a bit more attention in common commits. The tradeoff makes sense _specially_ if you are the integrator.

So I do git-commit -a, and typing that '-a' is small price to pay for the best SCM I've ever used ;-)

cheers,

martin

On Tue, 8 May 2007, Martin Langhoff wrote:

It is definitely true that some of the advantages of the way git does the index really start shinign when merging and you have content conflicts. What we've done to "git diff" really makes things a lot easier (and anybody who hasn't used "gitk --merge" after a content conflict really hasn't realized how *helpful* git is when merging content conflicts).

However, in all honesty, while the whole "index for merges" comes from pretty damn early in git history (the whole "stage number" thing appeared on April 15th 2005 - so it was about a week after the first release), it wasn't the original impetus of the way git works.

Git used explicit index updates from day 1, even before it did the first merge. It's simply how I've always worked. I tend to have dirty trees, with some random patch in my tree that I do *not* want to commit, because it's just a Makefile update for the next version (to remind me - I've released kernel versions too many times with an old version number, just because I forgot to update the Makefile).

Or other things like that - I have small test-patches in my tree that I want to build, but that I don't want to commit, and I end up doing big merges and whole patch-application sequences with such a dirty tree (obviously if the patch or merge wants to change that file, I then need to do something about that dirty state, but it happens surprisingly seldom).

So the whole "update stuff to be committed explicitly" ends up _really_ shining during a merge, but it actually is how I do non-merge development too.

			Linus

On 5/8/07, Linus Torvalds <torvalds@linux-foundation.org> wrote:

Totally, when merging git's approach is incredibly useful. gitk --merge and the resolved conflicts not appearing in the default git diff is great stuff.

For for small, simpleminded and mostly-linear development it's not that important. Of course, I use git on projects large and small, so I can understand it. For someone using it with a small mostly-linear project, the whole index thing is overkill, and the explanations pointless. I can understand people wondering WTF.

On a large project it's always a good idea to commit with explicit paths -- regardless of your SCM. As it happens, I have to use explicit paths with CVS, or it'll punish me by taking solid minutes to do a 2 file commit. I am sure that the mozilla and OpenOffice developers using CVS also commit with explicit paths. Life's too short to waste an hour.

(The times are from working on Moodle, hosted on SF.net with ~4K files, 700 directories.).

cheers,

m

On Tue, May 08, 2007 at 06:45:32AM CEST, Linus Torvalds wrote:

Hmm, does this really work so well for you guys? Because thanks to Mr. Murphy, in my case, when I have some custom Makefile tweak, I always need to commit some unrelated changes involving Makefile more often than usual, and so on; so in general case, file-level changes exclusion doesn't really work so well for me.

So this use of index seems to me really as a workaround for more fine-grained change control (in a similar way that rename following would be a workaround for lack of more fine-grained content moves tracking). I will have to look into git-gui's hunk-level control and maybe reimplement it in tig.

On Wed, 9 May 2007, Petr Baudis wrote:

Well, one thing is that I obviously mainly work on a relatively large project, and one that has been carefully de-centralized over a long long time, so the source code I work with - the kernel - may be more amenable to my workflow than most.

For example, we have long long since tried to avoid having central files that everybody changes - because it's such a pain to manage, even with good automated merging (and even more with central people still using just series of patches).

In other words, in well-maintained larger projects, you simply don't see those kinds of conflicts very often: people don't work on the same files very much. I regularly go for days, and easily merging hundreds of thousands of lines of changes, with a dirty tree, and the merges don't affect it at all.

And if I happen to hit a dirty file, the pull will just say "cannot merge", and I can stash away my changes, and just re-do. So the cost of a conflict in a dirty tree is very low when it *does* happen.

Many people seem to enjoy per-hunk commits, but I seldom do that. Maybe it's just because I'm *so* comfortable with diffs, that when I clean up an ugly sequence of commits, what I do is literally:

 - I make sure that my ugly sequence of commits is on some temporary 
   branch, but that the _end_result_ is good and clean (ie I will have 
   tested the end result fairly well, and made sure that there are no 
   debug statements etc crud left).

   I would call this branch something like "target", because the end 
   result of that branch is what I'm looking for - even if the commits in 
   the sequence that gets me there are individually ugly!

 - I just switch back to my starting point (and now I'm usually on 
   "master"), and do

	git diff -R target > diff

   to create a diff of my current tree (which is initially the starting 
   point) to the good result.

 - I actually edit the "diff" file by hand, and edit it down to the part I 
   actually want to commit as the first in the series. And then I just do 
   a "git-apply diff" to actually apply that part to my working tree.

 - I then edit any missing parts in the actual working tree (for example, 
   if there were mixed hunks that I want to get to in later commits, and I 
   edited out above, or that I need to partially undo), to do any 
   finishing touches.

 - I now have a tree I can compile and test, and has the "first part" of 
   the journey towards the final "target" state. If compiling/testing 
   shows that I missed something, I can still fix things, and/or go back 
   to doing another "git diff -R target" to see if I missed something).

 - I commit that first case, and repeat the sequence from step 2 (and 
   at every step, the "diff" file ends up shrinking and shrinking).

The above sounds like it's a complicated sequence, but it really isn't. Partly because I just am very comfortable with diffs indeed (probably more than most people), but partly because at all times "git diff" works fine to see what I've done, and what the diff to "target" is.

And unlike the "simpler" model of committing individual hunks with "git add -i" or something like that, my model is actually much superior! It means that I can actually test each stage individually, and make sure that the intermediate commits are good. It also allows me to edit up places where the diff mixes up two different things, and the intermediate result needs to be different from the final one.

Do I do this very often? No. Most of the time, the changes are separate enough that I can just commit one file at a time, and in fact, I can mix and match (ie I can do the above thing in the "big picture", but actually end up doing one substep where I do just one "diff and edit" phase, but then actually commit that as two things by just committing individual files separately when they are obviously independent changes).

But the above is literally what I did for the superproject support and for some other things where I want to send out the end result in a nice sequence of 5-6 patches, but when I was actually *developing* it I ended up making more mistakes, and I started out with 10 patches with some total braino's that I had to fix, or cleanups that I didn't do in the right sequence.

And I actually mix-and-match other ways of working too. For example, if some commit in my otherwise ugly "target" sequence was fine, I'll just cherry-pick it instead, and re-order things that way.

The point of this all is that the "git way" is actually very flexible. You can keep the tree dirty and not worry about it, and if you always think twice before you do "git commit -a" you won't be committing dirty state that you didn't intend to commit by mistake.

Of course, if you get so used to doing "git commit -a" that you just do it in your sleep, then the dirty tree model won't work for you, because you'll simply start committing stuff you didn't intend to commit when you're on auto-pilot. But the way I work, I basically always do

	git diff

to see what's in my tree, and I will only use the "-a" flag when I *consciously* think "ok, that's all one thing".

Btw, what goes hand-in-hand with this workflow is the nice ability to specify a subtree. So I'll have a dirty tree with two different test-things, but since one of them was a filesystem fix, and the other one was in the kernel, rather than give all the paths explicitly, I'd do

	git commit fs/

and it will automatically do the right thing (actually, I often end up using the two-stage "git add" + "git commit" thing, because one of the more common cases for me is that I'm going to commit a merge that I fixed up a conflict in, and then you have to do it that way).

			Linus

On Wed, 9 May 2007 08:52:09 -0700 (PDT), Linus Torvalds wrote: [Snip good description of rebuilding a branch to meet some "target" state.]

That's all really good stuff. And as you mentioned you sometimes use cherry-pick during this rebuilding, one can also use "git add -i" to help with splitting up an ugly commit that should have been multiple commit.

For example, a sequence might look like this, (I always use "desired" where you use target):

	git diff HEAD desired | git apply
	git add -i
	git commit
	git reset --hard
	# test here and commit --amend as needed

And repeat that as needed. It's really no different than your "edit the diff" approach. It's just using "add -i" instead of a text editor. But I do admit that the commit;reset;test;--amend sequence might seem a bit too awkward to some people.

This reminds me of a confusing semantic issue that came about with the "new" add. It can be quite natural to commit a single file in one step with:

	git commit some-file.c

or to do that in two steps with:

	git add some-file.c
	git commit

(which is particularly useful if one wants to add multiple files).

I recently found myself wanting to do a similar thing with a directory path. I can commit a path with:

	git commit path/

but I don't get anything at all like the same semantics if I do:

	git add path/
	git commit

(since "git add" will recursively add all untracked files under path/).

Now the "recursively add all files" behavior is older, and has been an essential part of git-add forever. But I found it to be not at all what I wanted in this case, (where I'm now trained to say "git add" to stage things into the index).

I don't know of any good fix for the problem now. Maybe I'll just need to remember to break out that old "git update-index" for a situation like this, but that sure feels clunky.

-Carl

Carl Worth wrote:

In the new version of git I *think* you can use "git add -u path/"

  'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--] <file>...

  -u::
        Update all files that git already knows about. This is what
        "git commit -a" does in preparation for making a commit.

(in v1.5.2-rc0, documented in v1.5.2-rc3).

On 5/9/07, Linus Torvalds <torvalds@linux-foundation.org> wrote:

Geez, this is similar [in nature, not scale] to what I've been doing. After reading about people "right-clicking on hunks in git-gui", I was convinced I needed to force myself to do more manipulations inside git itself. Hmm...

Maybe, in addition to [or in] the User Manual, git should have some workflow examples, which have been cribbed from various emails on this list?

Thanks,

On Wed, May 09, 2007 at 09:33:40AM -0700, Dana How wrote:

That's something several people have asked for, and I think it's a great idea--I just haven't personally had much time to get to it. But I'd happily take even very rough patches and help get them into shape.

The way I'd thought of doing it was having an "examples" section at the end of each chapter, with subsections for each individual example; see the one at the end of the "exploring git history" chapter:

	http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#history-examples

They shouldn't use the material introduced in the associated chapter, but it's also OK to introduce new commands (with references to the man pages) when their use in the example is pretty self-explanatory. (In fact, this is a great way to introduce more commands and options--git has so many that it would be tedious to try to be comprehensive, but they'd fit well in examples.)

The patch-editing stuff discussed above might fit best at the end of "rewriting history and maintaining patch series".

--b.

On Wed, May 09, 2007 at 07:18:45PM CEST, J. Bruce Fields wrote:

There is some workflow-related discussion accumulated over years in Documentation/howto/, some of them also already suffering quite of a bitrot. :-(

On Wed, May 09, 2007 at 07:26:22PM +0200, Petr Baudis wrote:

Yup. I think we should one-by-one update those and suck them into the manual. (Patches accepted!)

--b.

On Wed, 9 May 2007, Linus Torvalds wrote:

It only sounds like a complicated sequence because you didn't write a script to do it...

$ git checkout -b clean origin
$ git-refine target
  (edit the patch in the editor that pops up)
$ git-refine
Test changes and commit
$ make test
...
$ git commit
  (write message)
$ git-refine
  (edit the patch, etc)
  ...
$ git commit
$ git-refine
All done.

I actually wrote it years ago, but I couldn't describe my workflow well enough, so I didn't submit it. If everybody seems to be doing the same thing, I can submit my script...

	-Daniel
*This .sig left intentionally blank*

On Wed, 9 May 2007, Daniel Barkalow wrote:

Well, I actually think it sounds like a complicated sequence because I tried to explain what I do.

The "script" parts don't really end up being any smaller, and not scripting it actually means that I can (and often do) things outside of a strict scripting environment.

As mentioned, I not only mix it up with "git cherry-pick", but since I just use "git diff", I can - and do - things like pick only a certain set of files to diff and edit the patch on.

So it's an iterative process at several levels (the "outer" level is the act of actually committing each change, and iterating to the next one, while the "inner" level is often a sequence of "git diff" exploration), it's not very fixed.

For example, when I said that I do a 

	git diff -R target > diff

that's not strictly true. The "git diff -R" is useful for comparing the current working tree to another commit, but quite often I actually end up doing it differently, and doing it as

	git diff ..target file > diff
	.. edit ..
	git apply diff

or, if I don't need the edit (ie just the fact that I limit it to a single file is a sufficient "edit" in itself), I might just do

	git checkout target file

instead, which will fetch the whole file from the "target" branch (and also update it in the index, which may or may not actually be what I want, but that's a different issue).

So the "process" as far as I'm concerned is actually much more fluid than necessarily always working with diffs. Git gives you so many ways to do things like this, and I'm pretty comfortable with lots of them.

			Linus

Linus Torvalds <torvalds@linux-foundation.org> writes:

I obviously agree with this. As I said a few times I regret introducing "add -i" --- it encourages a wrong workflow, in that what you commit in steps never match what you had in the working tree and could have tested until the very end.

Junio C Hamano wrote:

On the other hand, not all changes require any testing at all. For example, if you're using git to manage documentation, it is totally reasonable to commit a fix for a simple spelling error in one part of a file while not committing an in-progress rewrite of another part.

-Steve

On Wed, 9 May 2007, Steven Grimm wrote:

Yeah, I don't think "git add -i" is a horrible flow - it just shouldn't be the only or the primary one (ie apparently it *is* the primary one for darcs, and that's a mistake!)

Of course, whether "git add -i" is a nice interface or not, I dunno. Personally, if I wanted to do hunk selection, I think I'd stick to something graphical where I can just click on the hunks. But that's just me.

		Linus

Linus Torvalds <torvalds@linux-foundation.org> writes:

Note that darcs has a way to test before commit even for partial commits. It re-creates your working tree, hardlinking unmodified files, and runs a command there as a precommit hook.

I still prefer the old good "you commit what's in the tree, and run whatever you want before commit", but their approach seems interesting also in this case.

Junio C Hamano <junkio@cox.net> wrote:

Which is why I'm considering shelving support (of some kind) in git-gui... but I'm probably not going to take away the current index view, nor am I going to take away the current hunk selection.

But I would like to make it easier for non-patching-editing gods (Linus) to pull hunks in from a shelf, test them, and commit them.

Said shelf probably would be another branch, much as Linus' nicely documented workflow does...

On Fri, May 11, 2007 at 12:06:49AM CEST, Shawn O. Pearce wrote:

FWIW, Cogito supports shelving of uncommitted changes when switching a branch (so that they are not retained through the switch but restored when you switch back to the original branch) by committing the local changes to refs/shelves/HEADNAME.

Hi,

On Tue, 8 May 2007, Martin Langhoff wrote:

You're saying that the main use of the index is to help merging. I have to disagree strongly.

When I have been chasing a bug all over the place, and finally found it, my working tree is a mess. Lots of assertions, lots of debugging statements, some of them commented out. So, now it is cleanup time, right?

The problem is that more often than not, I broke my fix while cleaning up.

Therefore, I now put all changed files into the index (git add -u), and clean up the files one by one, always checking with "git diff" and "git diff HEAD" what I still have to do.

Yes, very often I can just take the original version of a file (git reset --soft <file...> would be handy here), but it helped me quite a number of times to have my messed-up-but-working state in the index.

In a sense, I am using the index as the stash commit we talked about every once in a while.

Ciao, Dscho

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

Why not simply use a temporary branch for this? They're free, and you can diff just as easily, if not more. And you don't risk losing it if you slip with a command.

Hi,

On Mon, 14 May 2007, David Kågedal wrote:

Because it is much faster to work with the index?

Ciao, Dscho

Matthieu Moy <Matthieu.Moy@imag.fr> writes:

As promised, here's a FAQ entry on the wiki:

http://git.or.cz/gitwiki/GitFaq#head-3aa45c7d75d40068e07231a5bf8a1a0db9a8b717

Feel free to correct it.

Anyway, thanks for the interesting discussion.

Hi,

As a newbie, I'm agree with Matthieu: the Git's index is surprising for people coming from CVS/SVN (mindless?) world. So a good documentation about this, even in tutorials, is really important.

In order to improve my productivity with Git, and in order to avoid traps around moving from SVN to Git, I often use the Git Emacs mode. It is really usefull for beginners as it works similarly for CVS, SVN and Git: synthetic view of all modifications, easy selection of what will be commited... The biggest drawback of this "porcelain": using it, you do not understand the Git's index philosophy.

On 2007-05-07 13:40:33 +0200, Guilhem Bonnefille wrote:

git-gui is a good tool here (so good, in fact, that this is the second time today I spam the list about it). It shows very pedagogically the diff between HEAD and index, and the diff between index and working dir, and allows you to point and click your way to committing precisely the subset of changes you intended to commit. As an added bonus, it's perfectly usable even if you don't know anything about emacs.

Karl Hasselström <kha@treskal.com> writes:

Please be sure to _always_ include a URL whenever you are spamming.

Hi,

On Mon, 7 May 2007, Guilhem Bonnefille wrote:

So, you are not only a newbie, but you have to unlearn some CVS braindamage.

I don't know how to make it even more prominent that CVS users should read a special introduction first. AFAICT such a hint is in all the appropriate places. (I mean, you would not expect to be able to fly a plane, just because you have learnt to drive a car, wouldn't you?)

Ciao, Dscho

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

Well, people worried that documentation and command set before 1.5.0 exposed index too much, making learning curve too steep by having one extra thing people need to learn before starting to be productive with git. Now post 1.5.0 people are confused, quite rightly, that they are not told about index early enough.

I am not sure where to strike the right balance should be.

Let alone flying. Just taxiing straight was hard for me until I shook the habit I picked up from driving a car.

  Hi,

On Mon, May 07, 2007 at 02:55:13PM CEST, Johannes Schindelin wrote:

  http://www.kernel.org/pub/software/scm/git/docs/tutorial.html does not
talk about anything like that (it links to "Git for CVS users" but
that's really just about importing from CVS and the shared repository
workflow).

  On the other hand, I think the tutorial linked above gives quite a
clear explanation of git commit -a, git add etc. Guilhem, what do you
find missing in the tutorial about this topic?

On Mon, 7 May 2007, Guilhem Bonnefille wrote:

I think that the confusing thing isn't really the index, but the fact that git, by default, will make commits where the content in the commit is different from the content in the working directory. (In fact, you can use git-hash-object --stdin and git-update-index --cacheinfo to do a commit which shares no content at all with any present or past state of the working directory!)

In other version control systems, you have to use some option or argument to make that kind of non-matching commit (and you're generally limited in how your commits can fail to match the working directory). I think the confusion is that git requires an option to say that you want the commit to match the working directory, as opposed to creating a non-matching commit, which is generally the more advanced and more unusual case.

I think this is why people mostly get to understand the index by way of using it to resolve a conflicted merge: in that case, you have to make the index match the working directory before committing, and the index tracks your progress in reaching this state, which is the intuitive use of the index in normal situations.

	-Daniel
*This .sig left intentionally blank*

"Guilhem Bonnefille" <guilhem.bonnefille@gmail.com> writes:

And it's broken as well. If you "update" in the emacs mode you cannot do a "git commit" in a terminal without manually running "git update-index" first.

I think an emacs-mode that is closer to git-gui would be better, and closer to the git philosophy

On 2007-05-14 17:57:30 -0700, David Kågedal wrote:

I agree. (But for the record, I find the existing Emacs mode tremendously useful too. It's just that in some circumstances, you can get confused if you don't know what you're doing.)

On Fri, 11 May 2007, Junio C Hamano wrote:

I'm sorry I haven't checked this before writing, especially that information in the synopsis contradict a bit the information in the `-u' option description:

Documentation/git-add.txt:

  SYNOPSIS
  --------
  'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--] <file>...

  -u::
        Update all files that git already knows about. This is what
        "git commit -a" does in preparation for making a commit.

I should have checked the facts before following the synopsis.

I think however that "git add -u dir/" could be quite useful; it is not needed to have `-u' and explicit paths incompatibile. I wouldn't change the fact that you can say "git add -u" and do not need "git add -u ." (like in the case without `-u' switch: you need "git add ." to 'add' all unignored files).

Below there is a patch which corrects synopsis for git add; unless you want to go the route of allowing "git add -u dir/"...

-- >8 --
From: Jakub Narebski <jnareb@gmail.com>
Date: Fri, 11 May 2007 13:22:13 +0200
Subject: [PATCH] Documentation: Correct synopsis for git-add command

Change SYNOPISIS section of Documentation/git-add.txt to mark it explicitely that "-u option and explicit paths are incompatible", and that "add --interactive does not take any parameters".

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 Documentation/git-add.txt |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

Jakub Narebski <jnareb@gmail.com> writes:

What does "git commit -a" do?  Does it take paths?

I tend to agree, and I think that change should not be too difficult.

Also it might make sense to have "git commit" use it in the "git-commit --only $paths" codepath. I dunno.

Junio C Hamano wrote:

I was mislead by synopsis, which reads:

  'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--] <file>...

It looks from it like -u is _not_ incompatibile with explicit paths; moreover it looks like explicit path is _required_.

So do you want to accept my patch for git-add documentation for now,
or rather the replacement patch below? Well, best with the patch that
changes -u to be able to work with explicit codepath...
 

Didn't you mean "git commit --include $paths" codepath? IIRC --only codepath deals with temporary index...

-- >8 --
From: Jakub Narebski <jnareb@gmail.com>
Date: Sat, 12 May 2007 01:05:01 +0200
Subject: [PATCH] Documentation: Correct synopsis for git-add command

Change SYNOPISIS section of Documentation/git-add.txt to mark it explicitely that -u option does not need explicit paths, and that "add --interactive does not take any parameters".

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 Documentation/git-add.txt |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

Jakub Narebski <jnareb@gmail.com> writes:

I do not think this is correct; does -u take optionally path and when path is ambiguous you can add -- to disambiguate?

Honestly, I would rather not sprinkle synopsis with too many nested parentheses and brackets, which only makes it harder to see without giving a clear "this combines with that but is not compatible with the other" information. Adding comment to the section that begins with "-u::" that says "... commit -a; this option does not take any paths parameters." would be cleaner, and easier to understand.

Of course, I would prefer a patch to allow use of paths with -u even more, but that is what I already said ;-).

Junio C Hamano wrote:

[...] With *current* implementation you should take previous patch, amended, with the following synopsis:

-'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--] <file>... +'git-add' [-n] [-v] [-f] (-u | [--] <file>...) +'git-add' (--interactive | -i)

The following synopsis is for such case:

-'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--] <file>... +'git-add' [-n] [-v] [-f] (-u [[--] <file>...] | [--] <file>...) +'git-add' (--interactive | -i)

This is for "-u take optionally path and when path is ambiguous you can add -- to disambiguate", for example if you have '--interactive' file.

Junio C Hamano wrote:

This synopisis is for _after_ patch mentioned above. If you don't like too complicated (too deeply nested) expression in synopsis, it could always be written as:

-'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--] <file>... +'git-add' [-n] [-v] [-f] [--] <file>... +'git-add' [-n] [-v] [-f] -u [[--] <file>...]

or something like that