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

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

[Matthieu Moy]

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,

-- 
Matthieu

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

[Johannes Schindelin]

Hi,

On Sun, 6 May 2007, Matthieu Moy wrote:

> [...]
>
> % 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).

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

> In both cases, I can't really see the benefit.

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

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

[Matthieu Moy]

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

> Hi,
>
> On Sun, 6 May 2007, Matthieu Moy wrote:
>
>> [...]
>>
>> % 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).
>
> Have you tried "git status" _without_ "-a"?

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

>> In both cases, I can't really see the benefit.
>
> The benefit is a clear distinguishing between DWIM and low level. The 
> index contains _exactly_ what you told it to contain. 

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

> By forcing users to use "-a" with "git commit",

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

> you make it clear that a separate update steo is involved,

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.

> and if you made an error (which you see from the file list), you can
> abort, and start over with the original index.

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

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

[Junio C Hamano]

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

> 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.

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.

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

[Petr Baudis]

On Sun, May 06, 2007 at 07:43:31PM CEST, Junio C Hamano wrote:
> 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 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.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
Ever try. Ever fail. No matter. // Try again. Fail again. Fail better.
		-- Samuel Beckett

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

[Johannes Schindelin]

Hi,

On Wed, 9 May 2007, Petr Baudis wrote:

> On Sun, May 06, 2007 at 07:43:31PM CEST, Junio C Hamano wrote:
> > 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 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.

:-) 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

[PATCH] git-commit: Reformat log messages provided on commandline

[Petr Baudis]

  Hi,

On Wed, May 09, 2007 at 03:57:28PM CEST, Johannes Schindelin wrote:
> 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.

  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(-)

diff --git a/git-commit.sh b/git-commit.sh
index f28fc24..28cbb55 100755
--- a/git-commit.sh
+++ b/git-commit.sh
@@ -432,7 +432,7 @@ fi
 
 if test "$log_message" != ''
 then
-	echo "$log_message"
+	echo "$log_message" | fmt
 elif test "$logfile" != ""
 then
 	if test "$logfile" = -


-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
Ever try. Ever fail. No matter. // Try again. Fail again. Fail better.
		-- Samuel Beckett

Re: [PATCH] git-commit: Reformat log messages provided on commandline

[Matthieu Moy]

Petr Baudis <pasky@suse.cz> writes:

> -	echo "$log_message"
> +	echo "$log_message" | fmt

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.

-- 
Matthieu

Re: [PATCH] git-commit: Reformat log messages provided on commandline

[Petr Baudis]

On Wed, May 09, 2007 at 04:59:03PM CEST, Matthieu Moy wrote:
> Petr Baudis <pasky@suse.cz> writes:
> 
> > -	echo "$log_message"
> > +	echo "$log_message" | fmt
> 
> 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)

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 "Pasky" Baudis
Stuff: http://pasky.or.cz/
Ever try. Ever fail. No matter. // Try again. Fail again. Fail better.
		-- Samuel Beckett

Re: [PATCH] git-commit: Reformat log messages provided on commandline

[Matthieu Moy]

Petr Baudis <pasky@suse.cz> writes:

> 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.

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 ...)

-- 
Matthieu

Re: [PATCH] git-commit: Reformat log messages provided on commandline

[Johannes Schindelin]

Hi,

On Wed, 9 May 2007, Petr Baudis wrote:

> On Wed, May 09, 2007 at 03:57:28PM CEST, Johannes Schindelin wrote:
> > 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.
> 
>   oh, indeed - good point. cg-commit uses fmt to format the message, I
> think git-commit should do the same;

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

Re: [PATCH] git-commit: Reformat log messages provided on commandline

[Junio C Hamano]

Petr Baudis <pasky@suse.cz> writes:

> diff --git a/git-commit.sh b/git-commit.sh
> index f28fc24..28cbb55 100755
> --- a/git-commit.sh
> +++ b/git-commit.sh
> @@ -432,7 +432,7 @@ fi
>  
>  if test "$log_message" != ''
>  then
> -	echo "$log_message"
> +	echo "$log_message" | fmt
>  elif test "$logfile" != ""

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?

Re: [PATCH] git-commit: Reformat log messages provided on commandline

[Jakub Narebski]

Junio C Hamano wrote:

> 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.
[...]
> 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?

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?
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

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

[Dana How]

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:
> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
>
> > Hi,
> >
> > On Sun, 6 May 2007, Matthieu Moy wrote:
> >
> >> [...]
> >>
> >> % 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).
> >
> > Have you tried "git status" _without_ "-a"?
>
> Reading my message (including the last 5 words of the sentence you're
> quoting) would have told you that ;-).
>
> >> In both cases, I can't really see the benefit.
> >
> > The benefit is a clear distinguishing between DWIM and low level. The
> > index contains _exactly_ what you told it to contain.
>
> In other systems, commit commits _exactly_ the content of files on
> disk. And most people seem happy with that.
>
> > By forcing users to use "-a" with "git commit",
>
> Does this mean that the normal way to use "commit" is to use "-a"?
>
> > you make it clear that a separate update steo is involved,
>
> 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.
>
> > and if you made an error (which you see from the file list), you can
> > abort, and start over with the original index.
>
> 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
> -
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>


-- 
Dana L. How  danahow@gmail.com  +1 650 804 5991 cell

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

[Johannes Schindelin]

Hi Matthieu,

On Sun, 6 May 2007, Matthieu Moy wrote:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
> > On Sun, 6 May 2007, Matthieu Moy wrote:
> >
> >> [...]
> >>
> >> % 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).
> >
> > Have you tried "git status" _without_ "-a"?
> 
> Reading my message (including the last 5 words of the sentence you're 
> quoting) would have told you that ;-).

Okay, I rephrase the (badly worded) question:

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

> >> In both cases, I can't really see the benefit.
> >
> > The benefit is a clear distinguishing between DWIM and low level. The 
> > index contains _exactly_ what you told it to contain.
> 
> In other systems, commit commits _exactly_ the content of files on
> disk. And most people seem happy with that.

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.

> > By forcing users to use "-a" with "git commit",
> 
> Does this mean that the normal way to use "commit" is to use "-a"?

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.

> > you make it clear that a separate update steo is involved,
> 
> 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.

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.

> > and if you made an error (which you see from the file list), you can
> > abort, and start over with the original index.
> 
> 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

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

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

[Linus Torvalds]

On Sun, 6 May 2007, Matthieu Moy wrote:
> 
> 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.

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.

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

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:

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

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.

> 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).

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

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

[Matthieu Moy]

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

> On Sun, 6 May 2007, Matthieu Moy wrote:
>> 
>> 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.
>
> Yeah. You'd better get used to it, because it's fundamental.

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).

>  - 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". 

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

> 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.

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.

> [...] it basically could be used ass a definition of CVS: [...]
                                   ^^^
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,

-- 
Matthieu

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

[Linus Torvalds]

On Sun, 6 May 2007, Matthieu Moy wrote:
> 
> Well, git's index still tells more than "the content FOOBAR exists,
> somewhere". It also "contains", if not "points to", the file name.

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).

> 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".

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.

> > [...] it basically could be used ass a definition of CVS: [...]
>                                    ^^^
> 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 ;-).

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

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

[Julian Phillips]

On Sun, 6 May 2007, Matthieu Moy wrote:

> 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".

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.

> 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.

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

-- 
Julian

  ---
Your good nature will bring you unbounded happiness.

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

[Karl Hasselström]

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

> On Sun, 6 May 2007, Matthieu Moy wrote:
>
> > 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".
>
> 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-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.

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

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
      www.treskal.com/kalle

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

[Shawn O. Pearce]

Karl Hasselstr??m <kha@treskal.com> wrote:
> 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.

"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.

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

[Johannes Sixt]

"Shawn O. Pearce" wrote:
> But I'm glad someone else finds the hunk feature useful in
> git-gui.  I use it far too often myself.

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

-- Hannes

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

[Karl Hasselström]

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

> "Shawn O. Pearce" wrote:
>
> > But I'm glad someone else finds the hunk feature useful in
> > git-gui. I use it far too often myself.
>
> It it among the most-wanted features here. We discovered it only
> because Karl mentioned it yesterday. ;)

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 ...

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle

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

[J. Bruce Fields]

On Tue, May 08, 2007 at 12:28:36PM +0200, Karl Hasselström wrote:
> 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 ...

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.

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

[Karl Hasselström]

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

> On Tue, May 08, 2007 at 12:28:36PM +0200, Karl Hasselström wrote:
>
> > 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 ...
>
> 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....

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. :-)

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle

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

[J. Bruce Fields]

On Tue, May 08, 2007 at 04:53:11PM +0200, Karl Hasselström 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. :-)

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.

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

[Johannes Schindelin]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1593 bytes --]

Hi,

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

> On Tue, May 08, 2007 at 04:53:11PM +0200, Karl Hasselström 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. :-)
> 
> 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.

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

Ciao,
Dscho

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

[Karl Hasselström]

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

> Karl Hasselström <kha@treskal.com> wrote:
>
> > 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.
>
> "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.

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.

> I also want to let you revert hunks from the working directory copy.

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.

> 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. ;-)

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).

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

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
      www.treskal.com/kalle

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

[Shawn O. Pearce]

Karl Hasselstr??m <kha@treskal.com> wrote:
> 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.

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.

> > I also want to let you revert hunks from the working directory copy.
> 
> 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.

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 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.

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.
 
> 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).

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.  ;-)
 
-- 
Shawn.

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

[Johannes Schindelin]

Hi,

On Sun, 6 May 2007, Matthieu Moy wrote:

> Linus Torvalds <torvalds@linux-foundation.org> writes:
> 
> >  - 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". 
> 
> Well, git's index still tells more than "the content FOOBAR exists,
> somewhere". It also "contains", if not "points to", the file name.

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_.

> > 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.
> 
> 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 ...

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).

> 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".

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

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

[Matthieu Moy]

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

> 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.

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).

-- 
Matthieu

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

[Johannes Schindelin]

Hi,

On Mon, 7 May 2007, Matthieu Moy wrote:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
> > 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.
> 
> Well, this really depends on the use-case, size of commit, ...

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

> 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.

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

> 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.

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.

> 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).

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

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

[Petr Baudis]

  Hi,

On Mon, May 07, 2007 at 01:05:44PM CEST, Johannes Schindelin wrote:
> On Mon, 7 May 2007, Matthieu Moy wrote:
> 
> > Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> > 
> > > 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.
> > 
> > Well, this really depends on the use-case, size of commit, ...
> 
> Okay, so I use "-m" myself sometimes.

  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..
> 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.

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

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
Ever try. Ever fail. No matter. // Try again. Fail again. Fail better.
		-- Samuel Beckett

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

[Martin Langhoff]

On 5/7/07, Matthieu Moy <Matthieu.Moy@imag.fr> wrote:
> Linus Torvalds <torvalds@linux-foundation.org> writes:
>
> > On Sun, 6 May 2007, Matthieu Moy wrote:
> >>
> >> 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.
> >
> > Yeah. You'd better get used to it, because it's fundamental.
>
> Thanks a lot for the detailed explanations.

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

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

[Linus Torvalds]

On Tue, 8 May 2007, Martin Langhoff 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.

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

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

[Martin Langhoff]

On 5/8/07, Linus Torvalds <torvalds@linux-foundation.org> wrote:
> On Tue, 8 May 2007, Martin Langhoff 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.
>
> 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).

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.

> 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.

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

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

[Petr Baudis]

On Tue, May 08, 2007 at 06:45:32AM CEST, Linus Torvalds wrote:
> 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).

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.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
Ever try. Ever fail. No matter. // Try again. Fail again. Fail better.
		-- Samuel Beckett

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

[Linus Torvalds]

On Wed, 9 May 2007, Petr Baudis wrote:

> On Tue, May 08, 2007 at 06:45:32AM CEST, Linus Torvalds wrote:
> > 
> > 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).
> 
> 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.

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.

> 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.

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

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

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 2291 bytes --]

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.

> 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).

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

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Jakub Narebski]

Carl Worth wrote:

> 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.

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).
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

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

[Jakub Narebski]

On Fri, 11 May 2007, Junio C Hamano wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
> 
>> In the new version of git I *think* you can use "git add -u path/"
> 
> I know you meant well, but next time could you please check the
> fact before speaking?

> 		if (i < argc)
> 			die("-u and explicit paths are incompatible");

> The list is getting more and more cluttered recently, perhaps
> which is a good sign that more new people are actually using
> git.  Let's try to keep the signal quality of the messages on
> the list high.

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(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index ea27018..e5fc0da 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -7,7 +7,8 @@ git-add - Add file contents to the changeset to be committed next
 
 SYNOPSIS
 --------
-'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--] <file>...
+'git-add' [-n] [-v] [-f] [-u | [--] <file>...]
+'git-add' (--interactive | -i)
 
 DESCRIPTION
 -----------
-- 
1.5.1.3


-- 
Jakub Narebski
Poland

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

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> On Fri, 11 May 2007, Junio C Hamano wrote:
>> Jakub Narebski <jnareb@gmail.com> writes:
>> 
>>> In the new version of git I *think* you can use "git add -u path/"
>> 
>> I know you meant well, but next time could you please check the
>> fact before speaking?
>
>> 		if (i < argc)
>> 			die("-u and explicit paths are incompatible");
>
>> The list is getting more and more cluttered recently, perhaps
>> which is a good sign that more new people are actually using
>> git.  Let's try to keep the signal quality of the messages on
>> the list high.
>
> 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:
> ...
>   -u::
>         Update all files that git already knows about. This is what
>         "git commit -a" does in preparation for making a commit.

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

> I think however that "git add -u dir/" could be quite useful; it is
> not needed to have `-u' and explicit paths incompatibile.

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.

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

[Jakub Narebski]

Junio C Hamano wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
>> On Fri, 11 May 2007, Junio C Hamano wrote:
>>> Jakub Narebski <jnareb@gmail.com> writes:
>>> 
>>>> In the new version of git I *think* you can use "git add -u path/"
>>> 
>>> I know you meant well, but next time could you please check the
>>> fact before speaking?
>>
>>> 		if (i < argc)
>>> 			die("-u and explicit paths are incompatible");
>>
>>> The list is getting more and more cluttered recently, perhaps
>>> which is a good sign that more new people are actually using
>>> git.  Let's try to keep the signal quality of the messages on
>>> the list high.
>>
>> 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:
>> ...
>>   -u::
>>         Update all files that git already knows about. This is what
>>         "git commit -a" does in preparation for making a commit.
> 
> What does "git commit -a" do?  Does it take paths?

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_.

>> I think however that "git add -u dir/" could be quite useful; it is
>> not needed to have `-u' and explicit paths incompatibile.
> 
> I tend to agree, and I think that change should not be too
> difficult.

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...
 
> Also it might make sense to have "git commit" use it in the
> "git-commit --only $paths" codepath.  I dunno.

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(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index ea27018..3c6d431 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -7,7 +7,8 @@ git-add - Add file contents to the changeset to be committed next
 
 SYNOPSIS
 --------
-'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--] <file>...
+'git-add' [-n] [-v] [-f] (-u [[--] <file>...] | [--] <file>...)
+'git-add' (--interactive | -i)
 
 DESCRIPTION
 -----------
-- 
1.5.1.3

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

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

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

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 ;-).

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

[Jakub Narebski]

Junio C Hamano wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
> 
>> -'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--] <file>...
>> +'git-add' [-n] [-v] [-f] (-u [[--] <file>...] | [--] <file>...)
> 
> I do not think this is correct; does -u take optionally path and
> when path is ambiguous you can add -- to disambiguate?
[...]
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)

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

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.

-- 
Jakub Narebski
Poland

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

[Jakub Narebski]

Junio C Hamano wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
> 
> > -'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--] <file>...
> > +'git-add' [-n] [-v] [-f] (-u [[--] <file>...] | [--] <file>...)
> 
> 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 ;-).

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
-- 
Jakub Narebski
Poland

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

[Dana How]

On 5/9/07, Linus Torvalds <torvalds@linux-foundation.org> wrote:
>  - 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).

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,
-- 
Dana L. How  danahow@gmail.com  +1 650 804 5991 cell

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

[J. Bruce Fields]

On Wed, May 09, 2007 at 09:33:40AM -0700, Dana How 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?

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.

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

[Petr Baudis]

On Wed, May 09, 2007 at 07:18:45PM CEST, J. Bruce Fields wrote:
> On Wed, May 09, 2007 at 09:33:40AM -0700, Dana How 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?
> 
> 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".

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

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
Ever try. Ever fail. No matter. // Try again. Fail again. Fail better.
		-- Samuel Beckett

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

[J. Bruce Fields]

On Wed, May 09, 2007 at 07:26:22PM +0200, Petr Baudis wrote:
> There is some workflow-related discussion accumulated over years in
> Documentation/howto/, some of them also already suffering quite of a
> bitrot.  :-(

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

--b.

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

[Daniel Barkalow]

On Wed, 9 May 2007, Linus Torvalds wrote:

> 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.

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*

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

[Linus Torvalds]

On Wed, 9 May 2007, Daniel Barkalow wrote:
> 
> It only sounds like a complicated sequence because you didn't write a 
> script to do it...

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

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

[Junio C Hamano]

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

> And unlike the "simpler" model of committing individual hunks
> with "git add -i" or something like that, my model is actually
> much superior!

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.

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

[Steven Grimm]

Junio C Hamano wrote:
> 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.
>   

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

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

[Linus Torvalds]

On Wed, 9 May 2007, Steven Grimm wrote:

> Junio C Hamano wrote:
> > 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.
> >   
> 
> 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.

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

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

[Matthieu Moy]

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

> 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!)

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.

-- 
Matthieu

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

[Shawn O. Pearce]

Junio C Hamano <junkio@cox.net> wrote:
> Linus Torvalds <torvalds@linux-foundation.org> writes:
> 
> > And unlike the "simpler" model of committing individual hunks
> > with "git add -i" or something like that, my model is actually
> > much superior!
> 
> 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.

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...

-- 
Shawn.

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

[Petr Baudis]

On Fri, May 11, 2007 at 12:06:49AM CEST, Shawn O. Pearce 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...

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.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
Ever try. Ever fail. No matter. // Try again. Fail again. Fail better.
		-- Samuel Beckett

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

[Johannes Schindelin]

Hi,

On Tue, 8 May 2007, Martin Langhoff wrote:

> Heh. Making the index very visible makes sense when you are merging,

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

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

[David Kågedal]

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

> Hi,
>
> On Tue, 8 May 2007, Martin Langhoff wrote:
>
>> Heh. Making the index very visible makes sense when you are merging,
>
> 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.

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.

-- 
David Kågedal

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

[Johannes Schindelin]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 544 bytes --]

Hi,

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

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
> > 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.
> 
> 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.

Because it is much faster to work with the index?

Ciao,
Dscho

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

[Matthieu Moy]

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

> (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).

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.

-- 
Matthieu

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

[Guilhem Bonnefille]

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.

-- 
Guilhem BONNEFILLE
-=- #UIN: 15146515 JID: guyou@im.apinc.org MSN: guilhem_bonnefille@hotmail.com
-=- mailto:guilhem.bonnefille@gmail.com
-=- http://nathguil.free.fr/

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

[Karl Hasselström]

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

> 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.

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
      www.treskal.com/kalle

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

[David Kastrup]

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

> On 2007-05-07 13:40:33 +0200, Guilhem Bonnefille wrote:
>
>> 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.
>
> git-gui is a good tool here (so good, in fact, that this is the second
> time today I spam the list about it).

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

-- 
David Kastrup

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

[Johannes Schindelin]

Hi,

On Mon, 7 May 2007, Guilhem Bonnefille wrote:

> 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.

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

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

[Junio C Hamano]

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

> On Mon, 7 May 2007, Guilhem Bonnefille wrote:
>
>> 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.
>
> So, you are not only a newbie, but you have to unlearn some CVS 
> braindamage.

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.

> 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?)

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

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

[Petr Baudis]

  Hi,

On Mon, May 07, 2007 at 02:55:13PM CEST, Johannes Schindelin wrote:
> On Mon, 7 May 2007, Guilhem Bonnefille wrote:
> 
> > 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.
> 
> 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?)

  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?

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
Ever try. Ever fail. No matter. // Try again. Fail again. Fail better.
		-- Samuel Beckett

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

[Daniel Barkalow]

On Mon, 7 May 2007, Guilhem Bonnefille wrote:

> 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.

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*

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

[David Kågedal]

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

> 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.

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

-- 
David Kågedal

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

[Karl Hasselström]

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

> 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

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.)

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle