[PATCH] make 'git add' a first class user friendly interface to the index

[PATCH] make 'git add' a first class user friendly interface to the index

[Nicolas Pitre]

I personally think this is going to make the GIT experience lot more 
enjoyable for everybody.  This brings the power of the index up front 
using a proper mental model without talking about the index at all. See 
for example how all the technical discussion has been evacuated from the 
git-add man page.

Any content to be committed must be added together.  Whether that 
content comes from new files or modified files doesn't matter.  You just 
need to "add" it, either with git-add, or by providing git-commit with 
-a (for already known files only of course). No need for a separate 
command to distinguish new vs modified files please.  That would only 
screw the mental model everybody should have when using GIT.

Signed-off-by: Nicolas Pitre <nico@cam.org>

---

TODO:

maybe add a -f/--force argument to allow for adding ignored files 
instead of going through git-update-index.

maybe add --new-only and --known-only arguments if there is a real need 
to discriminate between new vs updated files.  I would not suggest 
against it though, because if someone really has such fancy and uncommon 
requirements he might just use git-update-index directly at that point.

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 6342ea3..ffa8446 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -3,7 +3,7 @@ git-add(1)
 
 NAME
 ----
-git-add - Add files to the index file
+git-add - Add file content to the changeset to be committed next
 
 SYNOPSIS
 --------
@@ -11,16 +11,31 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-A simple wrapper for git-update-index to add files to the index,
-for people used to do "cvs add".
-
-It only adds non-ignored files, to add ignored files use
+Contrary to other SCMs, with GIT you have to explicitly "add" all the
+changed file content you want to commit together to form a changeset
+with the 'add' command before using the 'commit' command.
+
+This is not only for adding new files.  Even modified files must be
+added to the set of changes about to be committed. This command can
+be performed multiple times before a commit. The 'git status' command
+will give you a summary of what is included for the next commit.
+
+Note: don't forget to 'add' a file again if you modified it after the
+first 'add' and before 'commit'. Otherwise only the previous added
+state of that file will be committed. This is because git tracks
+content, so what you're really 'add'ing to the commit is the *content*
+of the file in the state it is in when you 'add' it. Of course there are
+legitimate usage cases for not updating an already added file content
+in order to commit a previous file state, but in this case you better
+know what you're doing.
+
+This command only adds non-ignored files, to add ignored files use
 "git update-index --add".
 
 OPTIONS
 -------
 <file>...::
-	Files to add to the index (see gitlink:git-ls-files[1]).
+	Files to add content from.
 
 -n::
         Don't actually add the file(s), just show if they exist.
@@ -34,27 +49,12 @@ OPTIONS
 	for command-line options).
 
 
-DISCUSSION
-----------
-
-The list of <file> given to the command is fed to `git-ls-files`
-command to list files that are not registered in the index and
-are not ignored/excluded by `$GIT_DIR/info/exclude` file or
-`.gitignore` file in each directory.  This means two things:
-
-. You can put the name of a directory on the command line, and
-  the command will add all files in it and its subdirectories;
-
-. Giving the name of a file that is already in index does not
-  run `git-update-index` on that path.
-
-
 EXAMPLES
 --------
 git-add Documentation/\\*.txt::
 
-	Adds all `\*.txt` files that are not in the index under
-	`Documentation` directory and its subdirectories.
+	Adds content from all `\*.txt` files under `Documentation`
+	directory and its subdirectories.
 +
 Note that the asterisk `\*` is quoted from the shell in this
 example; this lets the command to include the files from
@@ -62,15 +62,17 @@ subdirectories of `Documentation/` directory.
 
 git-add git-*.sh::
 
-	Adds all git-*.sh scripts that are not in the index.
+	Considers adding content from all git-*.sh scripts.
 	Because this example lets shell expand the asterisk
 	(i.e. you are listing the files explicitly), it does not
-	add `subdir/git-foo.sh` to the index.
+	consider `subdir/git-foo.sh`.
 
 See Also
 --------
 gitlink:git-rm[1]
-gitlink:git-ls-files[1]
+gitlink:git-mv[1]
+gitlink:git-commit[1]
+gitlink:git-update-index[1]
 
 Author
 ------
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index fe4491d..8113d79 100644
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -87,14 +87,54 @@ thorough description.  Tools that turn commits into email, for
 example, use the first line on the Subject line and the rest of the
 commit in the body.
 
-To add a new file, first create the file, then
-
-------------------------------------------------
-$ git add path/to/new/file
-------------------------------------------------
-
-then commit as usual.  No special command is required when removing a
-file; just remove it, then tell `commit` about the file as usual.
+GIt tracks content not files
+----------------------------
+
+Contrary to other SCMs, with GIT you have to explicitly "add" all
+the changed _content_ you want to commit together to form a changeset.
+This can be done in a few different ways:
+
+1) By using 'git add <file_spec>...'
+ 
+   This can be performed multiple times before a commit.  Note that this
+   is not only for adding new files.  Even modified files must be
+   added to the set of changes about to be committed.  The "git status"
+   command gives you a summary of what is included so far for the
+   next commit.  When done you should use the 'git commit' command to
+   make it real.
+
+   Note: don't forget to 'add' a file again if you modified it after the
+   first 'add' and before 'commit'. Otherwise only the previous added
+   state of that file will be committed. This is because git tracks
+   content, so what you're really 'add'ing to the commit is the *content*
+   of the file in the state it is in when you 'add' it.
+
+2) By using 'git commit -a' directly
+
+   This is a quick way to automatically 'add' the content from all files
+   that were modified since the previous commit, and perform the actual
+   commit without having to separately 'add' them beforehand.  This will
+   not add content from new files i.e. files that were never added before.
+   Those files still have to be added explicitly before performing a
+   commit.
+
+But here's a twist. If you do 'git commit <file1> <file2> ...' then only
+the  changes belonging to those explicitly specified files will be
+committed, entirely bypassing the current "added" changes. Those "added"
+changes will still remain available for a subsequent commit though.
+
+There is a twist about that twist: if you do 'git commit -i <file>...'
+then the commit will consider changes to those specified files _including_
+all "added" changes so far.
+
+But for instance it is best to only remember 'git add' + 'git commit'
+and/or 'git commit -a'.
+
+No special command is required when removing a file; just remove it,
+then tell `commit` about the file as usual.
+
+Viewing the changelog
+---------------------
 
 At any point you can view the history of your changes using
 
diff --git a/builtin-add.c b/builtin-add.c
index febb75e..b3f9206 100644
--- a/builtin-add.c
+++ b/builtin-add.c
@@ -94,9 +94,6 @@ int cmd_add(int argc, const char **argv, const char *prefix)
 
 	newfd = hold_lock_file_for_update(&lock_file, get_index_file(), 1);
 
-	if (read_cache() < 0)
-		die("index file corrupt");
-
 	for (i = 1; i < argc; i++) {
 		const char *arg = argv[i];
 
@@ -131,6 +128,9 @@ int cmd_add(int argc, const char **argv, const char *prefix)
 		return 0;
 	}
 
+	if (read_cache() < 0)
+		die("index file corrupt");
+
 	for (i = 0; i < dir.nr; i++)
 		add_file_to_index(dir.entries[i]->name, verbose);
 
diff --git a/wt-status.c b/wt-status.c
index de1be5b..4b8b570 100644
--- a/wt-status.c
+++ b/wt-status.c
@@ -163,7 +163,7 @@ static void wt_status_print_changed_cb(struct diff_queue_struct *q,
 	int i;
 	if (q->nr)
 		wt_status_print_header("Changed but not updated",
-				"use git-update-index to mark for commit");
+				"use git-add on files to include for commit");
 	for (i = 0; i < q->nr; i++)
 		wt_status_print_filepair(WT_STATUS_CHANGED, q->queue[i]);

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> I personally think this is going to make the GIT experience lot more 
> enjoyable for everybody.  This brings the power of the index up front 
> using a proper mental model without talking about the index at all. See 
> for example how all the technical discussion has been evacuated from the 
> git-add man page.

I like the direction this is taking us.

The documentation update is in the same spirit with the sample
rewrite of 'git diff' manpage.  We might want to tweak the
wording to make this round of documentation updates consistent.

My preferences:

 - You used the word "changeset"; I am not sure that is a good
   wording.  The recent explanation I saw on the list and liked
   were "you _stage_ your changes to prepare for the next
   commit (footnote: the staging area is called 'the index')".
   My impression was that both extremes (Linus and Carl) are
   also Ok with this wording.

 - We keep the word "index", and not reword it to "stage" in the
   names of commands and options.  "to stage" is very good verb
   to explain the _concept_, but there is no need to use
   inconsistent wording Porcelain-ish and plumbing use to
   describe the entity used for staging.

   (1) New people need to learn the new concept anyway, and they
       are intelligent enough to learn what that new concept has
       been called for a long time in git-land at the same time.

       "The index" is the receiver of new contents to be staged;
       conversely, "to stage" is the act of registering contents
       to the index.

   (2) Majority of git old timers do not follow git mailing list
       discussion closely.  They already know the concept of
       "registering thing in the index".  We on the list are
       just about to agree to give a good short name, "to
       stage", for that action they have known about, in order
       for us to make it easier to explain to new people.  That
       should not affect the terminology the old timers are
       accustomed to and and trained their fingers with
       ("update-index", "diff --cached", "apply --index").

   (3) I hope nobody proposes to rename "update-index" to
       "update-stage" nor "diff-index" to "diff-stage"; that
       would break countless number of existing third party
       scripts old timers rely on and even new people would find
       on the web and tempted to try out, so plumbing level
       commands and options have to keep using the word 'index'.
       The option to 'git diff --cached' may need a new synonym
       to make things consistent, but the new synonym should be
       --index, not --staged.

   (4) New people will not stay newbies forever.  Using a
       consistent word for the entity used for staging for the
       next commit across Porcelain and plumbing is important.

> maybe add a -f/--force argument to allow for adding ignored files 
> instead of going through git-update-index.

Yup.

> maybe add --new-only and --known-only arguments if there is a real need 
> to discriminate between new vs updated files.  I would not suggest 
> against it though, because if someone really has such fancy and uncommon 
> requirements he might just use git-update-index directly at that point.

Borrow from "update-index --again", perhaps?

> +Contrary to other SCMs, with GIT you have to explicitly "add" all the
> +changed file content you want to commit together to form a changeset
> +with the 'add' command before using the 'commit' command.

... "before a new commit is made"; it is not an offence to leave
local changes outside the index.  Staging such changes to all
files is done using the "-a" flag and that is done "before a new
commit is made", but not "before using the 'commit' command" --
it is done at the same time.

> +This is not only for adding new files.  Even modified files must be
> +added to the set of changes about to be committed. This command can
> +be performed multiple times before a commit. The 'git status' command
> +will give you a summary of what is included for the next commit.
> +
> +Note: don't forget to 'add' a file again if you modified it after the
> +first 'add' and before 'commit'. Otherwise only the previous added
> +state of that file will be committed. This is because git tracks
> +content, so what you're really 'add'ing to the commit is the *content*
> +of the file in the state it is in when you 'add' it. Of course there are
> +legitimate usage cases for not updating an already added file content
> +in order to commit a previous file state, but in this case you better
> +know what you're doing.

May be we could hint the reader that a faster-to-type
alternative exists here.  Perhaps...

        Note: instead of doing 'git add' to stage the modified contents,
        you can ask 'git commit' to take all the modified contents in
        the working tree and stage them all before creating a commit
        with 'git commit -a'.

> +GIt tracks content not files

s/I/i/

> +But here's a twist. If you do 'git commit <file1> <file2> ...' then only
> +the  changes belonging to those explicitly specified files will be
> +committed, entirely bypassing the current "added" changes. Those "added"
> +changes will still remain available for a subsequent commit though.
> +
> +There is a twist about that twist: if you do 'git commit -i <file>...'
> +then the commit will consider changes to those specified files _including_
> +all "added" changes so far.
> +

I think there is another twist more deserving of mention than -i twist.
If you jump the index using --only, what is committed with that
commit becomes part of what is staged for the commit after that,
and in order to prevent data loss, we disallow this sequence:

	$ git checkout
	$ edit foo
        $ git add foo ;# your new add to update the existing entry.
	$ edit foo
        $ git commit foo

If we did not have the second edit (the behaviour is the same if
we did not have "git add foo" there), this commit:

 * commits the changes to 'foo' (not because you staged it
   earlier with 'git add', but only because you said "commit
   foo" to invoke the '--only' semantics), obviously;

 * updates 'foo' in the index to what was committed.

So if we allowed the above sequence to succeed, we would commit
the result of the second edit, and after the commit, the index
would have the result of the second edit.  We would lose the
state the user wanted to keep in the index while this commit
jumped the index, and that is why we disallow it.

> +But for instance it is best to only remember 'git add' + 'git commit'
> +and/or 'git commit -a'.
> +
> +No special command is required when removing a file; just remove it,
> +then tell `commit` about the file as usual.

I wonder if this sequence should do the same as "git rm -f foo":

	$ /bin/rm foo
        $ git add foo

That's one of the reasons I suggested 'checkin' instead of
'resolve', 'resolved', etc.  You check-in the removal of the
content from that path to the staging area, to go as a part of
the next commit.

> diff --git a/builtin-add.c b/builtin-add.c
> index febb75e..b3f9206 100644
> --- a/builtin-add.c
> +++ b/builtin-add.c
> @@ -94,9 +94,6 @@ int cmd_add(int argc, const char **argv, const char *prefix)
>  
>  	newfd = hold_lock_file_for_update(&lock_file, get_index_file(), 1);
>  
> -	if (read_cache() < 0)
> -		die("index file corrupt");
> -
>  	for (i = 1; i < argc; i++) {
>  		const char *arg = argv[i];
>  
> @@ -131,6 +128,9 @@ int cmd_add(int argc, const char **argv, const char *prefix)
>  		return 0;
>  	}
>  
> +	if (read_cache() < 0)
> +		die("index file corrupt");
> +
>  	for (i = 0; i < dir.nr; i++)
>  		add_file_to_index(dir.entries[i]->name, verbose);
>  

Hmph.  Fair enough.

> diff --git a/wt-status.c b/wt-status.c
> index de1be5b..4b8b570 100644
> --- a/wt-status.c
> +++ b/wt-status.c
> @@ -163,7 +163,7 @@ static void wt_status_print_changed_cb(struct diff_queue_struct *q,
>  	int i;
>  	if (q->nr)
>  		wt_status_print_header("Changed but not updated",
> -				"use git-update-index to mark for commit");
> +				"use git-add on files to include for commit");
>  	for (i = 0; i < q->nr; i++)
>  		wt_status_print_filepair(WT_STATUS_CHANGED, q->queue[i]);
>  	if (q->nr)

"use git-add to mark for commit, or use commit -a"?

I think the one source of confusion is "update-index" sounds as
if it is a command to "update the index" and as if you can leave
out "with what?" part to complete the order to the command.

We can use the word "add", thanks to your patch that enhances
the user level command, and I do not think the word "add" would
not induce that confusion.  It is more obvious that you have to
say "what to add".

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Alan Chandler]

On Friday 01 December 2006 22:31, Junio C Hamano wrote:
> Nicolas Pitre <nico@cam.org> writes:
...
>
> > +Contrary to other SCMs, with GIT you have to explicitly "add" all the
> > +changed file content you want to commit together to form a changeset
> > +with the 'add' command before using the 'commit' command.
>
> ... "before a new commit is made"; it is not an offence to leave
> local changes outside the index.  Staging such changes to all
> files is done using the "-a" flag and that is done "before a new
> commit is made", but not "before using the 'commit' command" --
> it is done at the same time.

How about

Contrary to other SCM's, with GIT you have to explicitly "add" the content 
that you want to commit before it is made; it is not an offence to leave 
changes outside the index if you want to leave them to a later commit.  
However if you do want all changes from your working tree to be added to the 
commit before it is made use the "-a" flag with the commit command and the 
content will be added just before the commit is made.


-- 
Alan Chandler

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Nicolas Pitre]

On Sat, 2 Dec 2006, Alan Chandler wrote:

> On Friday 01 December 2006 22:31, Junio C Hamano wrote:
> > Nicolas Pitre <nico@cam.org> writes:
> ...
> >
> > > +Contrary to other SCMs, with GIT you have to explicitly "add" all the
> > > +changed file content you want to commit together to form a changeset
> > > +with the 'add' command before using the 'commit' command.
> >
> > ... "before a new commit is made"; it is not an offence to leave
> > local changes outside the index.  Staging such changes to all
> > files is done using the "-a" flag and that is done "before a new
> > commit is made", but not "before using the 'commit' command" --
> > it is done at the same time.

Bleamphfff...  Nah.  There is certainly another way to formulate that.

> How about
> 
> Contrary to other SCM's, with GIT you have to explicitly "add" the content 
> that you want to commit before it is made; it is not an offence to leave 

Before what is made?

> changes outside the index if you want to leave them to a later commit.  
> However if you do want all changes from your working tree to be added to the 
> commit before it is made use the "-a" flag with the commit command and the 
> content will be added just before the commit is made.

Nah.  Too many concepts in the same paragraph.

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Nicolas Pitre]

On Fri, 1 Dec 2006, Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:
> 
> > I personally think this is going to make the GIT experience lot more 
> > enjoyable for everybody.  This brings the power of the index up front 
> > using a proper mental model without talking about the index at all. See 
> > for example how all the technical discussion has been evacuated from the 
> > git-add man page.
> 
> I like the direction this is taking us.
> 
> The documentation update is in the same spirit with the sample
> rewrite of 'git diff' manpage.  We might want to tweak the
> wording to make this round of documentation updates consistent.
> 
> My preferences:
> 
>  - You used the word "changeset"; I am not sure that is a good
>    wording.  

Why not?  It is a well defined word in the SCM context, and I really 
think what is built in the index before a commit is a changeset.

But actually I'd prefer "set of changes" even better as it is more 
independent of any definition "changeset" might have.

>    The recent explanation I saw on the list and liked
>    were "you _stage_ your changes to prepare for the next
>    commit (footnote: the staging area is called 'the index')".
>    My impression was that both extremes (Linus and Carl) are
>    also Ok with this wording.

Well... dunno.

>  - We keep the word "index", and not reword it to "stage" in the
>    names of commands and options.  "to stage" is very good verb
>    to explain the _concept_, but there is no need to use
>    inconsistent wording Porcelain-ish and plumbing use to
>    describe the entity used for staging.

First I don't know if "to stage" is such a good verb.  According to 
http://dictionary.reference.com/search?q=stage I think "stage" has just 
too many definitions already, and none of which really make me think of 
GIT's index.

>    (1) New people need to learn the new concept anyway, and they
>        are intelligent enough to learn what that new concept has
>        been called for a long time in git-land at the same time.
> 
>        "The index" is the receiver of new contents to be staged;
>        conversely, "to stage" is the act of registering contents
>        to the index.

In technical docs maybe.  But I don't see the need for this wording in 
the tutorial, not even in the "add" man page.

The best way not to confuse people and making the thing look 
not too complicated is to avoid making too many explanations especially 
when they're not necessary to operate the thing.  In my 
opinion the above quote fails that test.

There are two level of languages we must be aware of.  First there is 
language to explain how to use the thing.  Next there is language to 
explain how the thing works.  And _most_ people just want to know how to 
use the thing at first.  They don't care how it works under the hood 
until they have more confidence in their own ability to use the thing 
first.  So it is really important not to mix both levels of language.

In my opinion git-add man page and the tutorial should be about how to 
use the thing, not about how the thing works.  the git-update-index is 
where to talk about how the thing works.

And even on the technical level, the quote above is wrong.  Because if 
we talk about the actual index, it doesn't contain new content only.  
The index really contains everything, including current unmodified 
content.  So on a technical level (on the "how it works" level) we 
really "update" the index to reflect a different state, and in that 
context the git-update-index could not have a better name.  It really 
says what it does.

It's just that GIT users are simply not interested to know about it.  Of 
course all subscribers of this mailing list are, but not users.  What 
users want to know is how to use the tool and the best way IMHO is to 
simply create a mental model where "all changes always have to be added 
together explicitly before they are committed with git-add."  All the 
rest are shortcuts and variants derived from that fundamental user 
model.

And eventually the more intripid users will discover that what they were 
doing without knowing initially was "updating the index".

What we really want is for users to make use of the index.  This is our 
goal.  This is how GIT is superior.

But we don't need to force users to know about how it all works.  Not 
before they are confortable with using GIT first.

>    (2) Majority of git old timers do not follow git mailing list
>        discussion closely.  They already know the concept of
>        "registering thing in the index".  We on the list are
>        just about to agree to give a good short name, "to
>        stage", for that action they have known about, in order
>        for us to make it easier to explain to new people.  That
>        should not affect the terminology the old timers are
>        accustomed to and and trained their fingers with
>        ("update-index", "diff --cached", "apply --index").

I don't see the point.  Old timers are already familiar with GIT and 
with how it works so they don't really need the tutorial nor the basic 
command's man pages.  They won't be affected at all by any change of 
"how to use" model and terminology since they obviously don't have to 
learn how to use GIT.

>    (3) I hope nobody proposes to rename "update-index" to
>        "update-stage" nor "diff-index" to "diff-stage"; that
>        would break countless number of existing third party
>        scripts old timers rely on and even new people would find
>        on the web and tempted to try out, so plumbing level
>        commands and options have to keep using the word 'index'.

Absolutely not!  Doing that would be an horrible mistake.  First because 
of the reasons you mention above, and because IMHO "stage" isn't it at 
all.  The "how it works" model is perfectly sane and it is really about 
"updating the index".  Always was, always should.

>        The option to 'git diff --cached' may need a new synonym
>        to make things consistent, but the new synonym should be
>        --index, not --staged.

It should be --index, and it should also be --commit in my opinion.  The 
first for the "how it works" model, and the second for the "how to use" 
model.  Because what _users_ want is a diff of what is going to be 
committed if they type "git commit".  Therefore I think --commit is 
really the best it could be.  Let's avoid proxy meanings like "stage" or 
whatever and get to the point.  It is --index for obvious reasons, and 
it is --commit for another but as obvious reason.

>    (4) New people will not stay newbies forever.  Using a
>        consistent word for the entity used for staging for the
>        next commit across Porcelain and plumbing is important.

I disagree.  Porcelain is about usage. Plumbing is about programming.  
It is perfectly normal that they have different concepts and words.

> > maybe add a -f/--force argument to allow for adding ignored files 
> > instead of going through git-update-index.
> 
> Yup.
> 
> > maybe add --new-only and --known-only arguments if there is a real need 
> > to discriminate between new vs updated files.  I would not suggest 
> > against it though, because if someone really has such fancy and uncommon 

Sorry, "I would suggest against" is what I meant.

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Carl Worth]

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

On Fri, 01 Dec 2006 14:31:45 -0800, Junio C Hamano wrote:
>        "registering thing in the index".  We on the list are
>        just about to agree to give a good short name, "to
>        stage", for that action they have known about, in order
>        for us to make it easier to explain to new people.  That
>        should not affect the terminology the old timers are
>        accustomed to and and trained their fingers with
>        ("update-index", "diff --cached", "apply --index").

You can adopt a new, short name, and use it in both documentation
_and_ commands without breaking any habits. Just leave the
implementation of the old commands alone. You can even remove things
from the documentation, (or squirrel chunks away to "deprecated"
sections), if you're leaving things only for old-timers.

I've been _trying_ to make git easier to learn, and when there are two
commands, (update-index and "diff --cached"), that use different
terminology for the same concept, that's a road bump to learning.

Yes, _we_ all know that it's talking about the same thing. And we are
all an existence proof that people _can_ learn git as it is without
any changes. But I contend that more people could learn git more
easily if we worked to smooth things out like this.

But almost none of what I proposed should really make things harder on
experienced users. If we make the terminology of the command-set
consistent with the way we explain things in the tutorials and
documentation, then we're being that much nicer. I came up with
"stage" and "--staged" because over and over again I saw Linus and
other say things like "the index is easy to understand if you think of
it as a staging area."

Someone didn't like the use of "stage" as a verb. I'd be happy with
something else that's a nice, short verb that has a consistent
adjective to match. Currently, we have an unshort, non-verb
"update-index", a mismatched adjective "--cached" and a misplaced noun
"--index".

The proposal in the current thread of using "add" is an improvement on
the shortness side, and I am _delighted_ to see documentation
appearing that is focused on what the user wants to achieve and what
the user should expect to happen. So, Junio, please go ahead with
Nico's stuff here. It is an improvement over the current
situation. (And thanks, Nico, for fighting against having technical
details getting added to user-oriented documentation).

But I do still think it's a mistake to muddle the concepts of "adding"
a file and "staging edited content" for a file. In index terms, the
distinction is between adding a new path (and contents, of course) to
the index vs. just updating the contents for an existing path.

But it's not the index distinction that's interesting. It's that users
think of those operations differently. An "add" operation takes a
files out of the "untracked file" state as reported by git
status. That's a very different thing conceptually than updating the
contents of a file that is already being tracked by git. And if the
user thinks of an operation as being different, the command should
reflect that. There is a sense in which the user is always right here,
(since if the tool doesn't do what the user wants, the user just goes
somewhere else).

>        The option to 'git diff --cached' may need a new synonym
>        to make things consistent, but the new synonym should be
>        --index, not --staged.

I like consistency, so I agree that "diff --index" is an improvement
over "diff --cached", (and of course you can leave "diff --cached"
around forever).

The "--staged" thing only came up as I looked for a replacement for
"update-index" as a verb. We can just use "add" to, but it is a bit
awkward for the reasons I explained above.

> > maybe add a -f/--force argument to allow for adding ignored files
> > instead of going through git-update-index.
>
> Yup.

Yes, very nice.

> > maybe add --new-only and --known-only arguments if there is a real need
> > to discriminate between new vs updated files.  I would not suggest
> > against it though, because if someone really has such fancy and uncommon
> > requirements he might just use git-update-index directly at that point.

Please don't add --new-only and --known-only options to git add. The
fewer the options, the easier the command is for humans to learn.

The only place I can imagine --new-only or --known-only being useful
would be in a scripting situation, not manually typed on the command
line. And as you say, update-index already exists for that.

Please keep user-oriented commands focused on things that _users_
actually want to do.

> > +Contrary to other SCMs, with GIT you have to explicitly "add" all the
> > +changed file content you want to commit together to form a changeset
> > +with the 'add' command before using the 'commit' command.

I think we can explain the git model in positive terms that stand on
its own. People will learn the differences and appreciate how git is
better. So I'd just drop "Contrary to other SCMs". It's a really weak
form of pride to compare ourselves to other systems. We can do much
better by having the hubris to pretend no other systems exists.

> > +This is not only for adding new files.

I think this sentence shows the failing of the "add" naming. We having
to explicitly say here. Oh, and when we say "add" we don't mean what
you think of as "add", we mean something else. If we mean something
else, why don't we just call it something else?

> I think there is another twist more deserving of mention than -i twist.
> If you jump the index using --only, what is committed with that
> commit becomes part of what is staged for the commit after that,
> and in order to prevent data loss, we disallow this sequence:
[...]
> So if we allowed the above sequence to succeed, we would commit
> the result of the second edit, and after the commit, the index
> would have the result of the second edit.  We would lose the
> state the user wanted to keep in the index while this commit
> jumped the index, and that is why we disallow it.

Wow, this index stuff sure takes a lot of explaining. Why are users
better off having to grasp all of that stuff before they can
successfully add; edit; #oops, add again; and commit their files?

> I wonder if this sequence should do the same as "git rm -f foo":
>
> 	$ /bin/rm foo
>         $ git add foo

Argh. Please no. Update-index already exists. Let's not push all of
its semantics onto "add". Let's use "add" for when the user _actually_
wants to _add_ a file. Please? please?

> That's one of the reasons I suggested 'checkin' instead of
> 'resolve', 'resolved', etc.  You check-in the removal of the
> content from that path to the staging area, to go as a part of
> the next commit.

I think having "checkin" as a non-synonym for "commit" would be a big
mistake for new users. Different systems out there use those terms
interchangeably. Since git has something unique in its "index" or
"staging area" we're much better off sticking to unique terms for
describing it.

> "use git-add to mark for commit, or use commit -a"?
>
> I think the one source of confusion is "update-index" sounds as
> if it is a command to "update the index" and as if you can leave
> out "with what?" part to complete the order to the command.

Yes. Jesse Keating, for example, read the "use update-index"
suggestion from git-commit and was very confused why he didn't succeed
when he thought he was following instructions with:

	git update-index
	git commit

Maybe the above could be:

	Use "git add <files...>" then "git commit",
	or "git commit -a" to add and commit all tracked files.

But why are we even directing to "git add" here instead of just:

	What would you like to commit?

	Use "git commit <files..>" to commit some files
	or "git commit -a" to commit all files.

This doesn't teach the two-part, staged commit to the user at this
point, but that's perhaps OK.

Except it does still leave open the user confusion of:

	git add file1
	git commit
	"cool, that works"

	edit file1
	git add file2
	git commit
	"hmm, why didn't file1 get commited that time?!"

And the only answer we can give to the poor user is:

	Oh, "git add", (and "git commit" for that matter) don't do
	what you think they do. Go read the documentation and try
	again.

At least, with this latest round of updates, the "git add"
documentation will actually explain this stuff, (and not just say
"this is a wrapper for update-index"). But there are still a lot of
users that will say "I have to add the file over and over again?
That's bizarre." They won't be saying, "Oh, the git designers were so
brilliant to implement a system based entirely on file contents and
never treating filenames as an interesting entity separate from
content. Thank you so much!"

So, git still isn't "usable" by just picking up the commands and
running with them, learning more as they go along. Some potential
users get lost here. And that's too bad, because nothing in git's
model, (or even in functionality already existing in the command set),
is missing compared to what the user wants. They just didn't find it
by default.

Git _will_ be more learnable from the documentation, but it will still
leave a lot of users thinking it makes some simple things harder than
they should be. So other potential users get lost here. And that's too
bad too, because if they would stick with it a little, they could
learn things later on where git would make complex things simple,
(like conflict resolution).

If add really were uniquely about _adding_ files to be tracked,
(rather than just a short synonym for update-index), and if we tweaked
the default behavior of git-commit, we could fix these things. And
all the model and power of git would still exist and be ready to be
learned by anyone that wants it, (rather than only by those who manage
to get past snags like these).

-Carl

PS. Is there a twelve-steps program for people who can't let a thread
die? I really want to stop, and I keep telling myself I can stop
anytime I want.

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

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Junio C Hamano]

Carl Worth <cworth@cworth.org> writes:

>> > +Contrary to other SCMs, with GIT you have to explicitly "add" all the
>> > +changed file content you want to commit together to form a changeset
>> > +with the 'add' command before using the 'commit' command.
>
> I think we can explain the git model in positive terms that stand on
> its own. People will learn the differences and appreciate how git is
> better. So I'd just drop "Contrary to other SCMs".

I already committed Nico's on 'master', because all he said in
his response made sense, but this comment made me rewind it.  I
agree that we do not have to start with a "we are harder to
learn, we are different from what you know, you have been
warned."  I'll queue it for 'next'.

> Wow, this index stuff sure takes a lot of explaining. Why are users
> better off having to grasp all of that stuff before they can
> successfully add; edit; #oops, add again; and commit their files?

Jumping the index is not about that sequence.  It is about being
interrupted while doing something else, and committing a smaller
trivial change first that is independent from what you have been
doing.  Beginners do not have to do that "interrupted work"
sequence.

>> I wonder if this sequence should do the same as "git rm -f foo":
>>
>> 	$ /bin/rm foo
>>      $ git add foo
>
> Argh. Please no. Update-index already exists. Let's not push all of
> its semantics onto "add". Let's use "add" for when the user _actually_
> wants to _add_ a file. Please? please?

I do agree "adding the deletion" is a funny terminology.  But
this is a illustration that this part of proposed update to the
tutorial could be further improved:

+But for instance it is best to only remember 'git add' + 'git commit'
+and/or 'git commit -a'.
+
+No special command is required when removing a file; just remove it,
+then tell `commit` about the file as usual.

We say "you should add modified state again if you edit it again
after you added it" in a section before these sentences, and
encourage users to consistently say 'git add'.  Since we supply
"git rm" and "git mv" to make it convenient to remove/rename
files and index entries at the same time, I think it would be
better to say "Use add/rm/mv", not "don't worry about rm".

By the way, aren't people disturbed that "git rm" does not
default to "-f" -- I rarely use the command myself but that
makes it feel even more awkward that "git rm foo" does not
remove the file "foo".

> PS. Is there a twelve-steps program for people who can't let a thread
> die? I really want to stop, and I keep telling myself I can stop
> anytime I want.

Well, I think at least we are converging.

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Alan Chandler]

On Saturday 02 December 2006 06:54, Carl Worth wrote:
...
> The proposal in the current thread of using "add" is an improvement on
> the shortness side, and I am _delighted_ to see documentation
> appearing that is focused on what the user wants to achieve and what
> the user should expect to happen. So, Junio, please go ahead with
> Nico's stuff here. It is an improvement over the current
> situation. (And thanks, Nico, for fighting against having technical
> details getting added to user-oriented documentation).
>
> But I do still think it's a mistake to muddle the concepts of "adding"
> a file and "staging edited content" for a file. In index terms, the
> distinction is between adding a new path (and contents, of course) to
> the index vs. just updating the contents for an existing path.
>
> But it's not the index distinction that's interesting. It's that users
> think of those operations differently. An "add" operation takes a
> files out of the "untracked file" state as reported by git
> status. That's a very different thing conceptually than updating the
> contents of a file that is already being tracked by git. And if the
> user thinks of an operation as being different, the command should
> reflect that. There is a sense in which the user is always right here,
> (since if the tool doesn't do what the user wants, the user just goes
> somewhere else).
>
...
 
> 
> Except it does still leave open the user confusion of:
>
> 	git add file1
> 	git commit
> 	"cool, that works"
>
> 	edit file1
> 	git add file2
> 	git commit
> 	"hmm, why didn't file1 get commited that time?!"
>
> And the only answer we can give to the poor user is:
>
> 	Oh, "git add", (and "git commit" for that matter) don't do
> 	what you think they do. Go read the documentation and try
> 	again.
>
...
> If add really were uniquely about _adding_ files to be tracked,
> (rather than just a short synonym for update-index), and if we tweaked
> the default behavior of git-commit, we could fix these things. And
> all the model and power of git would still exist and be ready to be
> learned by anyone that wants it, (rather than only by those who manage
> to get past snags like these).

There is a conceptual difference between thinking that git-add is about adding 
a file and git-add adding the current state of a files content.  If your 
conceptual model is the first of these - then I can see why you see a problem 
with git-add being used to say a files contents have changed. 

However, if you regard the git-add command is "adding the current content of 
the file to a staging area" , and you say this is an SCM which by definition 
keeps the history of things once its been told about them I don't see why 
there is a need for a different name for the operation the first time and for 
the operation later.

Trying to put myself in the shoes of a newbie - if taught to use add in both 
ways up front - is to ask why git isn't clever enough to notice that I have 
changed the content of something it already knows about rather than having it 
to manually add it again.  

So I am with you that we need to effective teach

git add <filename>   #add content of filename to the SCM
#edit <filename>
git commit -a		#commit current state of all tracked content

first, and then move on to teach selective commiting

The benefit of one name rather than two is that its less to remember



-- 
Alan Chandler

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Carl Worth]

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

On Fri, 01 Dec 2006 23:54:38 -0800, Junio C Hamano wrote:
> > Wow, this index stuff sure takes a lot of explaining. Why are users
> > better off having to grasp all of that stuff before they can
> > successfully add; edit; #oops, add again; and commit their files?
>
> Jumping the index is not about that sequence.  It is about being
> interrupted while doing something else, and committing a smaller
> trivial change first that is independent from what you have been
> doing.  Beginners do not have to do that "interrupted work"
> sequence.

I guess my point is, the only arguments I've heard against changing the
default behavior of "git commit" are:

1. It's always been the way it is

  This is a legitimate concern, yes. It might justify a big bump to
  git's version number, or a new configuration option that the
  old-timers would set, or maybe the "default" I want could be a a new
  configuration option that would be set by default for new clones.

  Whatever. There's an inertia problem here, but that hasn't been the
  strong push-back I've been getting.

2. Doing anything other than the way it is would "deny the index"

  This argument has been made forcefully, and again and again.

  But I don't think it stands at all. The current behavior of
  "git-commit files..." denies the index just as much. Just look at
  the documentation for git-commit. It starts out with a technical,
  index-based description:

	Updates the index file for given paths, or all modified files
	if -a is specified, and makes a commit object.

  Now, that description doesn't explicitly say from _what_ the commit
  object is created, but a natural reading would be "from the updated
  index". And historically, that is exactly what "git commit files..."
  did. I'm sure this wording is fairly old.

  However, today what "git commit files..." does today is very
  different. It's a bit hard to track it down in the man page, but
  eventually you end up with:

	"Commit only the files specified on the command line."

  What does that even mean in terms of the index? I don't even know
  the precise details. And I don't think there's even a very clean way
  to describe it. (The documentation already starts to get a bit messy
  where it has to describe that certain index states will make "git
  commit files..." balk completely).

  So "git commit files..." already "denies the index" just as much as
  my proposed default behavior for "git commit". Why? Because it's
  _useful_, that's why. The old "git commit files..." behavior was
  much more consistent in terms of index manipulation, but Junio got a
  scalding email from Linus when he suggested reverting that behavior.

  If you try to think about all the index manipulations of "git commit
  files..." you'll actually get fairly confused. But has there been
  some problem with people failing to be able to learn the index as a
  result? Has anyone ever even run into this confusion?  No. Because,
  "git commit files..." does exactly what you actually _want_ to do,
  and that operation is really easy to describe without any confusion:

	"Commit only the files specified on the command line."

So, we can come up with just as short descriptions for the other
useful git commands:

	commit -a	Commit all files tracked by git

	commit		Commit all files as they exist in the index

Think about when the behavior of these commands is the same, and think
about when they are different. If they're different, think about what
situations make that difference _useful_, what does the user _want_ to
do? And finally, what did the user have to do to arrive at that
situation?

 * The commands are the same when resolving a merge.

 * The commands are different when explicitly staging a commit. This
   difference is useful---a point which has also been made forcefully,
   again and again. This situation arises when a user explicitly
   executes a command to stage something into the index, (historically
   with "update-index" and now proposed for "add").

 * The commands are different after adding a new file to be tracked by
   git for the first time. This difference is not useful. This
   situation arises whenever a file is added and subsequently
   edited. It's not necessarily the case that the user is _trying_ to
   do any staged commit, (and most commonly the user is not).

The recent "git add" conversation conflates these last two use cases,
which is a bit problematic because one is useful to the user while the
other is not.

> We say "you should add modified state again if you edit it again
> after you added it" in a section before these sentences, and
> encourage users to consistently say 'git add'.

I think this is a mistake for documentation that will be encountered
early by new users, (as git-add is one of the first things a user must
use if starting with git from scratch as opposed to through a
clone). The problem is that all the talk of "git add + git commit"
easily leads to the impression that there's more work to do in git
than in any other system that anyone may have ever encountered.

Now, there isn't actually more work, and we can explain that later,
"you will most commonly not use the sequence explained above, but will
instead use 'git commit -a' which will perform both steps for you".

This is the kind of sentence in documentation which just screams that
there's a user-interface problem. Why do we explain how to do
something only to say a moment later that user's won't do that? The
reason is because we _have_ to explain git-add that way or else the
current semantics of git-add + git-commit can be very confusing.

Let's just eliminate that confusion, drop the stuff from the
docs. that make git seem like it's harder to use than anything else on
the planet, and save the discussion of the index for a section in the
documentation that deals with something the user is wanting to do that
actually _benefits_ from the index.

> By the way, aren't people disturbed that "git rm" does not
> default to "-f" -- I rarely use the command myself but that
> makes it feel even more awkward that "git rm foo" does not
> remove the file "foo".

Yes, it's usually a bug that it doesn't delete the file by
default. This one's my doing, but I was thinking of an actual
situation that I had been in, that of wanting to undo an "add". For
example:

	git add file1
	git add file2
	# Oh, wait, I should commit these independently
	git rm file2
	git commit -m "add file1"
	git add file2
	git commit -m "add file2"

So one way to fix this would be to make "git rm" delete the file if it
is consistent in working-tree and HEAD and to leave it there
otherwise. The message could be something like:

	Note: file <foo> has uncommitted changes, leaving it in
	the working tree as an untracked file.

Then, -f could still be useful as a way to force file deletion even in
this case.

> Well, I think at least we are converging.

I'm glad you feel that way. I know I've been something of a pest
recently, (and yes, Linus, I do often get weary of pests that want to
throw out the fundamental strengths of a system like X).

Maybe think of it this way: I've been arguing on behalf of
brain-damaged users. Git's got the cure for them, but they're not
ready to sign up for that kind of brain surgery when they can see it
coming. If we can subdue them with a more gentle introduction, ("start
counting the everyday git commands backwards from 10 to 1"), then
we'll have their brains and can do everything we want to them.

And I really think the re-training can be painless---I don't think the
proposals I'm making will setup any nasty surprises down the road.

-Carl

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

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Jakub Narebski]

Junio C Hamano wrote:

>  - We keep the word "index", and not reword it to "stage" in the
>    names of commands and options.  "to stage" is very good verb
>    to explain the _concept_, but there is no need to use
>    inconsistent wording Porcelain-ish and plumbing use to
>    describe the entity used for staging.
> 
>    (1) New people need to learn the new concept anyway, and they
>        are intelligent enough to learn what that new concept has
>        been called for a long time in git-land at the same time.
> 
>        "The index" is the receiver of new contents to be staged;
>        conversely, "to stage" is the act of registering contents
>        to the index.

I think we should refer to "the index" as "the staging area [for commits]",
at least the first time (it is a bit longish to use it later).
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Jakub Narebski]

Junio C Hamano wrote:

> By the way, aren't people disturbed that "git rm" does not
> default to "-f" -- I rarely use the command myself but that
> makes it feel even more awkward that "git rm foo" does not
> remove the file "foo".

But _only_ if file is unmodified. I think that "git rm" meaning
"remove this file from version control, but not from working area"
is a good thing; if you want to remove file, just /usr/bin/rm it.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Han-Wen Nienhuys]

Jakub Narebski escreveu:
> Junio C Hamano wrote:
> 
>> By the way, aren't people disturbed that "git rm" does not
>> default to "-f" -- I rarely use the command myself but that
>> makes it feel even more awkward that "git rm foo" does not
>> remove the file "foo".
> 
> But _only_ if file is unmodified. I think that "git rm" meaning
> "remove this file from version control, but not from working area"
> is a good thing; if you want to remove file, just /usr/bin/rm it.

In my workflow,  I regularly get bitten by this: 

I do 

  git checkout devel
  git rm src/foo.cc
  git commit src/foo.cc    # or whatever -a -i --difficult option is necessary

  git checkout stable

     ...barf: trying to overwrite untracked src/foo.cc file..


I think for the default to remove from the working area is better. 

FWIW, I consider it annoyance with CVS as well 

-- 
 Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Carl Worth]

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

On Sat, 2 Dec 2006 08:28:57 +0000, Alan Chandler wrote:
> There is a conceptual difference between thinking that git-add is about adding
> a file and git-add adding the current state of a files content.

Yes, there is.

>                                                                 If your
> conceptual model is the first of these - then I can see why you see a problem
> with git-add being used to say a files contents have changed.

Yes. (And of course, I personally understand the second conceptual
model. But there are a lot of "brain-damaged" people out there.)

> However, if you regard the git-add command is "adding the current content of
> the file to a staging area" , and you say this is an SCM which by definition
> keeps the history of things once its been told about them I don't see why
> there is a need for a different name for the operation the first time and for
> the operation later.

Yes, that's also true. Once you know the model then you wouldn't need
two different commands. One can certainly get by with just the
functionality of "update-index" for everything.

> Trying to put myself in the shoes of a newbie - if taught to use add in both
> ways up front - is to ask why git isn't clever enough to notice that I have
> changed the content of something it already knows about rather than having it
> to manually add it again.

Yes, and "put myself in the shoes of a newbie" is what I've been doing
through the whole conversation. That's why I keep coming across as so
stubbornly stupid in these threads, ("why can't Carl just understand
how git works?!").

> So I am with you that we need to effective teach
>
> git add <filename>   #add content of filename to the SCM
> #edit <filename>
> git commit -a		#commit current state of all tracked content
>
> first, and then move on to teach selective commiting

Yes. That's the only way to avoid this confusion.

So all of the conditions above, ("if your conceptual model is", "if
you regard the git-add command", "if taught to use git-add up front",
"if we effectively teach 'commit -a' first"), are barriers to learning
git. We can't guarantee these are all met for new users, and when
they're not, the users can get confused.

If git's model imposes the requirement, "we should first teach one
thing, then move on to teach a subsequent thing", it would be just
that much nicer if the commands themselves could help us do that,
(because the default would do the thing they would need first, and
then the user has to explicitly do _something_ else to get the
subsequent thing).

See? I'm just trying to make the command set more naturally provide
the same flow of learning that we've been proposing for the tutorial.

-Carl

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

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Jakub Narebski]

Carl Worth wrote:

> If git's model imposes the requirement, "we should first teach one
> thing, then move on to teach a subsequent thing", it would be just
> that much nicer if the commands themselves could help us do that,
> (because the default would do the thing they would need first, and
> then the user has to explicitly do _something_ else to get the
> subsequent thing).
> 
> See? I'm just trying to make the command set more naturally provide
> the same flow of learning that we've been proposing for the tutorial.

Not exactly. For example more user-friendly is "mv -i" than "mv",
but noone proposes to make "mv -i" default (well, you can alias
"mv" to "mv -i" in shell, while you cannot alias "commit" to "commit -a"
in git).

So i think having the default geared towards advanced users and not
newbie users is O.K.

By the way, I find it a bit annoying that "git commit" outputs
git-status output (possibly multi-line if you have many untracked
but unignored files in working area) before "nothing to commit".

P.S. Is there a difference between "git commit ." and "git commit -a"?
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Alan Chandler]

On Saturday 02 December 2006 16:49, Carl Worth wrote:
> On Sat, 2 Dec 2006 08:28:57 +0000, Alan Chandler wrote:
> > There is a conceptual difference between thinking that git-add is about
> > adding a file and git-add adding the current state of a files content.
>
> Yes, there is.
>
> >                                                                 If your
> > conceptual model is the first of these - then I can see why you see a
> > problem with git-add being used to say a files contents have changed.
>
> Yes. (And of course, I personally understand the second conceptual
> model. But there are a lot of "brain-damaged" people out there.)
>
> > However, if you regard the git-add command is "adding the current content
> > of the file to a staging area" , and you say this is an SCM which by
> > definition keeps the history of things once its been told about them I
> > don't see why there is a need for a different name for the operation the
> > first time and for the operation later.
>
> Yes, that's also true. Once you know the model then you wouldn't need
> two different commands. One can certainly get by with just the
> functionality of "update-index" for everything.
...
> So all of the conditions above, ("if your conceptual model is", "if
> you regard the git-add command", "if taught to use git-add up front",
> "if we effectively teach 'commit -a' first"), are barriers to learning
> git. We can't guarantee these are all met for new users, and when
> they're not, the users can get confused.
>

The argument I was _trying_ to make was that we should teach the second 
conceptual model not the first one AND stick with just the git add command 
(in response to your (Carl's) statement earlier in the thread that there 
needs to be two separate commands) .  My if statements were to illustrate 
that there are two fundamental ways of looking at this, not lots of ifs that 
newbies would have to consider.  We should up-front (in the tutorial, in 
appropriate man pages) use the one conceptual model (and I also like Junio's 
argument that git should take an aggressive stance of this is how the 
conceptual model is rather than the "contrary to ..." approach).



-- 
Alan Chandler

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Nicolas Pitre]

On Sat, 2 Dec 2006, Alan Chandler wrote:

> The argument I was _trying_ to make was that we should teach the second 
> conceptual model not the first one AND stick with just the git add command 
> (in response to your (Carl's) statement earlier in the thread that there 
> needs to be two separate commands) .  My if statements were to illustrate 
> that there are two fundamental ways of looking at this, not lots of ifs that 
> newbies would have to consider.  We should up-front (in the tutorial, in 
> appropriate man pages) use the one conceptual model (and I also like Junio's 
> argument that git should take an aggressive stance of this is how the 
> conceptual model is rather than the "contrary to ..." approach).

Agreed.

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Nicolas Pitre]

On Sat, 2 Dec 2006, Carl Worth wrote:

> If git's model imposes the requirement, "we should first teach one
> thing, then move on to teach a subsequent thing", it would be just
> that much nicer if the commands themselves could help us do that,
> (because the default would do the thing they would need first, and
> then the user has to explicitly do _something_ else to get the
> subsequent thing).

Since I've been thinking about this issue I've come to the conclusion 
that making commit -a the default for commit is not a good thing.

Why? Because we really want newbies to be tricked into using the index.

And teaching about the different ways to update the index in the 
tutorial right after the first commit example is IMHO the best thing to 
do.

Making commit -a the default would make it possible for newbies to 
get along for a long while ignoring the usage model of git and that is 
bad.

I think the idea is really to make "git commit" with a clean index more 
clueful to the user.  Right now it only says "use git-update-index to 
mark for commit" which is really not that helpful, and actually the 
point of failure with the example newbie problem you pointed out.

There is a compromise to reach.  Sure the _user_ needs a proper model to 
use the tool without being bothered with technical implementation or 
architecture details.  But we still need newbies to get into the git 
model nevertheless, and having a default for git-commit geared towards 
making it bump free for new users is not the way to go I think.  The 
"nothing to commit" message needs to be way more helpful with better 
guidance and the git-commit default behavior should be overcome.

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Nicolas Pitre]

On Sat, 2 Dec 2006, Alan Chandler wrote:

> So I am with you that we need to effective teach
> 
> git add <filename>   #add content of filename to the SCM
> #edit <filename>
> git commit -a		#commit current state of all tracked content
> 
> first, and then move on to teach selective commiting

I think that's pretty much what my patch to the tutorial does.

The tutorial talks about:

	1) git init-db

	2) git add .

	3) git commit

	4) modifying some files then git diff

	5) git commit file1 file2, or git commit -a

Then goes the discussion about what git add does and why.  It is quite 
early in the tutorial and making it earlier would be a bit premature.  
Let's have the user make his first simple commit while blindly 
following the instructions before going with the 
actual usage model.  At that point,since we just mentioned "git commit 
file1 file2" or "git commit -a" will the user be in the proper mindset 
to wonder why not using plain "git commit"... and incidentally the whole 
explanation is there to follow immediately.

I'm reworking my patch with suggestions that have been posted so let's 
hope it'll be even clearer.

Re: [PATCH] make 'git add' a first class user friendly interface to the index

[Nicolas Pitre]

On Fri, 1 Dec 2006, Junio C Hamano wrote:

> > +Contrary to other SCMs, with GIT you have to explicitly "add" all the
> > +changed file content you want to commit together to form a changeset
> > +with the 'add' command before using the 'commit' command.
> 
> ... "before a new commit is made"; it is not an offence to leave
> local changes outside the index.  Staging such changes to all
> files is done using the "-a" flag and that is done "before a new
> commit is made", but not "before using the 'commit' command" --
> it is done at the same time.

Sorry but I don't think this is a good idea to tell that.  At least not 
here.  Opening all the possibilities too fast at once is a good way to 
create distrust.  Let's focus on what the user needs to know about the 
add command only.  

The newbie that becomes not so newbie aftera while will deduce that he 
actually _can_ leave local changes outside the index and he'll go "wow, 
that is cool!" especially if he deduce this by himself.  And that 
deduction will happen in time while using the tool when the opportunity 
for leaving local changes outside the index arises which is a much 
better way to grasp the power of the index than by just being told about 
it.

AS to the commit -a ... I think it is better to refer to the commit man 
page once it has been refactored with the writeup you posted yourself 
and simply direct the user with "You may also have a look at the 
git-commit documentation for alternative ways to add content to a 
commit."

> > +This is not only for adding new files.  Even modified files must be
> > +added to the set of changes about to be committed. This command can
> > +be performed multiple times before a commit. The 'git status' command
> > +will give you a summary of what is included for the next commit.
> > +
> > +Note: don't forget to 'add' a file again if you modified it after the
> > +first 'add' and before 'commit'. Otherwise only the previous added
> > +state of that file will be committed. This is because git tracks
> > +content, so what you're really 'add'ing to the commit is the *content*
> > +of the file in the state it is in when you 'add' it. Of course there are
> > +legitimate usage cases for not updating an already added file content
> > +in order to commit a previous file state, but in this case you better
> > +know what you're doing.
> 
> May be we could hint the reader that a faster-to-type
> alternative exists here.  Perhaps...

Perhaps not.

> > +GIt tracks content not files
> 
> s/I/i/

Yup

> > +But here's a twist. If you do 'git commit <file1> <file2> ...' then only
> > +the  changes belonging to those explicitly specified files will be
> > +committed, entirely bypassing the current "added" changes. Those "added"
> > +changes will still remain available for a subsequent commit though.
> > +
> > +There is a twist about that twist: if you do 'git commit -i <file>...'
> > +then the commit will consider changes to those specified files _including_
> > +all "added" changes so far.
> > +
> 
> I think there is another twist more deserving of mention than -i twist.

Actually I removed the -i twist entirely.  It is simply too much for the 
context of the tutorial and it is of no advantage for a newbie to even 
know that -i exists just yet.

> If you jump the index using --only, what is committed with that
> commit becomes part of what is staged for the commit after that,
> and in order to prevent data loss, we disallow this sequence:
> 
> 	$ git checkout
> 	$ edit foo
>         $ git add foo ;# your new add to update the existing entry.
> 	$ edit foo
>         $ git commit foo
> 
> If we did not have the second edit (the behaviour is the same if
> we did not have "git add foo" there), this commit:
> 
>  * commits the changes to 'foo' (not because you staged it
>    earlier with 'git add', but only because you said "commit
>    foo" to invoke the '--only' semantics), obviously;
> 
>  * updates 'foo' in the index to what was committed.
> 
> So if we allowed the above sequence to succeed, we would commit
> the result of the second edit, and after the commit, the index
> would have the result of the second edit.  We would lose the
> state the user wanted to keep in the index while this commit
> jumped the index, and that is why we disallow it.

Great.  This is perfectly fine behavior.  But I think this definitely 
doesn't belong in the tutorial.  the probability for a newbie to perform 
the above sequence is rather low, and even then the explanation belongs 
in the failure message not in the tutorial.  It can be as short as 
"Please see git-commit man page and look for xyz for explanation about 
this failure" if the inline explanation would be too long.

> > +But for instance it is best to only remember 'git add' + 'git commit'
> > +and/or 'git commit -a'.
> > +
> > +No special command is required when removing a file; just remove it,
> > +then tell `commit` about the file as usual.
> 
> I wonder if this sequence should do the same as "git rm -f foo":
> 
> 	$ /bin/rm foo
>         $ git add foo

Well I think Linus' suggestions about git-rm are really sane.  When 
git-rm has been updated then it could be mentioned here, along with 
git-mv.  In the mean time I simply removed that paragraph.

[PATCH v2] make 'git add' a first class user friendly interface to the index

[Nicolas Pitre]

I personally think this is going to make the GIT experience lot more
enjoyable for everybody.  This brings the power of the index up front
using a proper mental model without talking about the index at all. See
for example how all the technical discussion has been evacuated from the
git-add man page.

Any content to be committed must be added together.  Whether that
content comes from new files or modified files doesn't matter.  You just
need to "add" it, either with git-add, or by providing git-commit with
-a (for already known files only of course). No need for a separate
command to distinguish new vs modified files please.  That would only
screw the mental model everybody should have when using GIT.

Signed-off-by: Nicolas Pitre <nico@cam.org>
---
 Documentation/git-add.txt  |   55 +++++++++++++++++++++++--------------------
 Documentation/tutorial.txt |   46 ++++++++++++++++++++++++++++++++----
 builtin-add.c              |    6 ++--
 wt-status.c                |    2 +-
 4 files changed, 73 insertions(+), 36 deletions(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 6342ea3..411adad 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -3,7 +3,7 @@ git-add(1)
 
 NAME
 ----
-git-add - Add files to the index file
+git-add - Add file content to the changeset to be committed next
 
 SYNOPSIS
 --------
@@ -11,16 +11,32 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-A simple wrapper for git-update-index to add files to the index,
-for people used to do "cvs add".
-
-It only adds non-ignored files, to add ignored files use
+All the changed file content to be committed together in a single set
+of changes must be "added" together with the 'add' command before using
+the 'commit' command.
+
+This is not only for adding new files.  Even modified files must be
+added to the set of changes about to be committed. This command can
+be performed multiple times before a commit. The 'git status' command
+can be used to obtain a summary of what is included for the next commit.
+
+Note: don't forget to 'add' a file again if you modified it after the
+first 'add' and before 'commit'. Otherwise only the previous added
+state of that file will be committed. This is because git tracks
+content, so what you're really 'add'ing to the commit is the *content*
+of the file in the state it is in when you 'add' it. Of course there are
+legitimate usage cases for not updating an already added file content
+in order to commit a previous file state if you really know what
+you're doing.
+
+This command only adds non-ignored files, to add ignored files use
 "git update-index --add".
 
+
 OPTIONS
 -------
 <file>...::
-	Files to add to the index (see gitlink:git-ls-files[1]).
+	Files to add content from.
 
 -n::
         Don't actually add the file(s), just show if they exist.
@@ -34,27 +50,12 @@ OPTIONS
 	for command-line options).
 
 
-DISCUSSION
-----------
-
-The list of <file> given to the command is fed to `git-ls-files`
-command to list files that are not registered in the index and
-are not ignored/excluded by `$GIT_DIR/info/exclude` file or
-`.gitignore` file in each directory.  This means two things:
-
-. You can put the name of a directory on the command line, and
-  the command will add all files in it and its subdirectories;
-
-. Giving the name of a file that is already in index does not
-  run `git-update-index` on that path.
-
-
 EXAMPLES
 --------
 git-add Documentation/\\*.txt::
 
-	Adds all `\*.txt` files that are not in the index under
-	`Documentation` directory and its subdirectories.
+	Adds content from all `\*.txt` files under `Documentation`
+	directory and its subdirectories.
 +
 Note that the asterisk `\*` is quoted from the shell in this
 example; this lets the command to include the files from
@@ -62,15 +63,17 @@ subdirectories of `Documentation/` directory.
 
 git-add git-*.sh::
 
-	Adds all git-*.sh scripts that are not in the index.
+	Considers adding content from all git-*.sh scripts.
 	Because this example lets shell expand the asterisk
 	(i.e. you are listing the files explicitly), it does not
-	add `subdir/git-foo.sh` to the index.
+	consider `subdir/git-foo.sh`.
 
 See Also
 --------
 gitlink:git-rm[1]
-gitlink:git-ls-files[1]
+gitlink:git-mv[1]
+gitlink:git-commit[1]
+gitlink:git-update-index[1]
 
 Author
 ------
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index fe4491d..0069fc3 100644
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -87,14 +87,48 @@ thorough description.  Tools that turn commits into email, for
 example, use the first line on the Subject line and the rest of the
 commit in the body.
 
-To add a new file, first create the file, then
 
-------------------------------------------------
-$ git add path/to/new/file
-------------------------------------------------
+Git tracks content not files
+----------------------------
+
+With git you have to explicitly "add" all the changed _content_ you
+want to commit together. This can be done in a few different ways:
+
+1) By using 'git add <file_spec>...'
+ 
+   This can be performed multiple times before a commit.  Note that this
+   is not only for adding new files.  Even modified files must be
+   added to the set of changes about to be committed.  The "git status"
+   command gives you a summary of what is included so far for the
+   next commit.  When done you should use the 'git commit' command to
+   make it real.
+
+   Note: don't forget to 'add' a file again if you modified it after the
+   first 'add' and before 'commit'. Otherwise only the previous added
+   state of that file will be committed. This is because git tracks
+   content, so what you're really 'add'ing to the commit is the *content*
+   of the file in the state it is in when you 'add' it.
+
+2) By using 'git commit -a' directly
+
+   This is a quick way to automatically 'add' the content from all files
+   that were modified since the previous commit, and perform the actual
+   commit without having to separately 'add' them beforehand.  This will
+   not add content from new files i.e. files that were never added before.
+   Those files still have to be added explicitly before performing a
+   commit.
+
+But here's a twist. If you do 'git commit <file1> <file2> ...' then only
+the  changes belonging to those explicitly specified files will be
+committed, entirely bypassing the current "added" changes. Those "added"
+changes will still remain available for a subsequent commit though.
+
+But for instance it is best to only remember 'git add' + 'git commit'
+and/or 'git commit -a'.
+
 
-then commit as usual.  No special command is required when removing a
-file; just remove it, then tell `commit` about the file as usual.
+Viewing the changelog
+---------------------
 
 At any point you can view the history of your changes using
 
diff --git a/builtin-add.c b/builtin-add.c
index febb75e..b3f9206 100644
--- a/builtin-add.c
+++ b/builtin-add.c
@@ -94,9 +94,6 @@ int cmd_add(int argc, const char **argv, const char *prefix)
 
 	newfd = hold_lock_file_for_update(&lock_file, get_index_file(), 1);
 
-	if (read_cache() < 0)
-		die("index file corrupt");
-
 	for (i = 1; i < argc; i++) {
 		const char *arg = argv[i];
 
@@ -131,6 +128,9 @@ int cmd_add(int argc, const char **argv, const char *prefix)
 		return 0;
 	}
 
+	if (read_cache() < 0)
+		die("index file corrupt");
+
 	for (i = 0; i < dir.nr; i++)
 		add_file_to_index(dir.entries[i]->name, verbose);
 
diff --git a/wt-status.c b/wt-status.c
index de1be5b..4b8b570 100644
--- a/wt-status.c
+++ b/wt-status.c
@@ -163,7 +163,7 @@ static void wt_status_print_changed_cb(struct diff_queue_struct *q,
 	int i;
 	if (q->nr)
 		wt_status_print_header("Changed but not updated",
-				"use git-update-index to mark for commit");
+				"use git-add on files to include for commit");
 	for (i = 0; i < q->nr; i++)
 		wt_status_print_filepair(WT_STATUS_CHANGED, q->queue[i]);
 	if (q->nr)
-- 
1.4.4.1.gc419-dirty

Re: [PATCH v2] make 'git add' a first class user friendly interface to the index

[Alan Chandler]

On Sunday 03 December 2006 05:33, Nicolas Pitre wrote:
...
> +But here's a twist. If you do 'git commit <file1> <file2> ...' then only
> +the  changes belonging to those explicitly specified files will be
> +committed, entirely bypassing the current "added" changes. Those "added"
> +changes will still remain available for a subsequent commit though.
> +
> +But for instance it is best to only remember 'git add' + 'git commit'
> +and/or 'git commit -a'.
> +

The "But for instance" seems a strange way of saying that.

How about

However, for normal usage you only have to remember 'git add' + 'git commit' 
and/or 'git commit -a'.


-- 
Alan Chandler