threads / rfc / 43071

[RFC] A unique way to express "all" (vs "add vs "update") ?

Subject: [RFC] A unique way to express "all" (vs "add vs "update") ?

## tl;dr

6 messages between Dec 15, 2006 and Dec 18, 2006.

replies: 5people: 4as markdown or json

Jerome Lovy· Dec 15, 2006, 11:38 UTC · lore
Hi,

While I am very happy with the refactorings undertaken with regard to "git add/git commit" (both for UI and documentation), I am still a little confused by the different ways I seem to find to express the idea "I want to add (sort of) all file contents".

To be more specific, I find the following in the current documentation:
git add <dir>
	"adds content from all files under <dir>  directory and its
	subdirectories."
	(as interpreted from the "EXAMPLES" section of the git-add
	man-page)
	(BTW, could this <dir> usage be documented in the SYNOPSIS and
	DESCRIPTION sections (admittedly at a 2nd rank after the
	currently documented usage)  as well as in the EXAMPLES ?
	Besides this reference sections would probably include the
	<dir>/<regexp> usage that I've not mentioned here for the sake
	of simplicity.)
	
	Moreover, the tutorial documents the typical usage "git add ."
git commit -a|--all
	"automatically stage files that have been modified and deleted,
	but new files you have not told git about are not affected."

Granted, the latter semantics for "all" is not exactly the same as the former. Nonetheless, I think it would be very nice to only have to memorize one way to express "all".

To this end, I would be very happy with the following: (X-mas is coming soon, isn't it ;-) )

git add <dir>
	same semantics
git commit -a|--add <files>
	"adds content from the specified files before committing
	(files that are already tracked have their current content
	staged)"
git commit -a|--add <dir>
	"adds content from all files under <dir>  directory and its
	subdirectories before committing"
	(once again, for simplification of my explanations, I omit the
	<dir>/<regexp> usage here)
git commit -u|--update <dir>
	"automatically stage files that have been modified and deleted
	under <dir>  directory and its subdirectories, but new files you
	have not told git about are not affected."
	(once again, for simplification of my explanations, I omit the
	<dir>/<regexp> usage here)
	(This would allow the typical usage "git commit -u ." which is
	barely longer than the current "git commit -a")

For interface completeness, "git commit -u|--update <files>" could also exist but would probably be of no use.

To sum up, "all" would be consistently expressed with the <dir> syntax.
"git commit -a" would not mean "--all" anymore. Lastly, a distinction
would be made between "--add" and "--update":
- "git commit -add" would have the same semantics as "git add"
- "git commit --update" on the other hand would only affect the files
   already tracked

Thank you for your patient attention. Jérôme Lovy

Andreas Ericsson· Dec 15, 2006, 12:09 UTC · re: Jerome Lovy · lore

Re: [RFC] A unique way to express "all" (vs "add vs "update") ?

Jerome Lovy wrote:
Show 31 quoted lines
> Hi,
> 
> While I am very happy with the refactorings undertaken with regard to
> "git add/git commit" (both for UI and documentation), I am still a
> little confused by the different ways I seem to find to express the idea
> "I want to add (sort of) all file contents".
> 
> To be more specific, I find the following in the current documentation:
> 
> git add <dir>
>     "adds content from all files under <dir>  directory and its
>     subdirectories."
>     (as interpreted from the "EXAMPLES" section of the git-add
>     man-page)
>     (BTW, could this <dir> usage be documented in the SYNOPSIS and
>     DESCRIPTION sections (admittedly at a 2nd rank after the
>     currently documented usage)  as well as in the EXAMPLES ?
>     Besides this reference sections would probably include the
>     <dir>/<regexp> usage that I've not mentioned here for the sake
>     of simplicity.)
>     
>     Moreover, the tutorial documents the typical usage "git add ."
> 
> git commit -a|--all
>     "automatically stage files that have been modified and deleted,
>     but new files you have not told git about are not affected."
> 
> Granted, the latter semantics for "all" is not exactly the same as the
> former. Nonetheless, I think it would be very nice to only have to 
> memorize one way to express "all".
>

But the former isn't "all"; It's a specific directory, although "." happens to *look* like "all", you can run "git add ." in a subdirectory inside the repository and it won't mean "all" anymore. Likewise, you can say "git commit ." from a subdirectory and have it commit all changes to all tracked files under that directory.

Show 24 quoted lines
> To this end, I would be very happy with the following:
> (X-mas is coming soon, isn't it ;-)  )
> 
> git add <dir>
>     same semantics
> 
> git commit -a|--add <files>
>     "adds content from the specified files before committing
>     (files that are already tracked have their current content
>     staged)"
> 
> git commit -a|--add <dir>
>     "adds content from all files under <dir>  directory and its
>     subdirectories before committing"
>     (once again, for simplification of my explanations, I omit the
>     <dir>/<regexp> usage here)
> 
> git commit -u|--update <dir>
>     "automatically stage files that have been modified and deleted
>     under <dir>  directory and its subdirectories, but new files you
>     have not told git about are not affected."
>     (once again, for simplification of my explanations, I omit the
>     <dir>/<regexp> usage here)
> 
But this isn't "commit" at all. It's "git add".
Show 10 quoted lines
>     (This would allow the typical usage "git commit -u ." which is
>     barely longer than the current "git commit -a")
> 
> For interface completeness, "git commit -u|--update <files>" could also
> exist but would probably be of no use.
> 
> To sum up, "all" would be consistently expressed with the <dir> syntax.
> "git commit -a" would not mean "--all" anymore. Lastly, a distinction
> would be made between "--add" and "--update":
> - "git commit -add" would have the same semantics as "git add"

This is bollocks. git commit should commit things. We'll be in some serious trouble if "git commit -a" stops working the way it has and starts just adding things to index.

> - "git commit --update" on the other hand would only affect the files
>   already tracked
>

I fail to see what you're after with the changes propsed in this mail. Is there a use-case you've encountered where you wanted to do something that wasn't possible, or easy enough, that made you post this?

Unless it's a very, very good reason I most urgently think we're better off keeping the current "git commit -a" behaviour.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Junio C Hamano· Dec 15, 2006, 21:55 UTC · re: Andreas Ericsson · lore

Re: [RFC] A unique way to express "all" (vs "add vs "update") ?

Andreas Ericsson <ae@op5.se> writes:
Show 18 quoted lines
> Jerome Lovy wrote:
> ...
> But this isn't "commit" at all. It's "git add".
>
>>     (This would allow the typical usage "git commit -u ." which is
>>     barely longer than the current "git commit -a")
>>
>> For interface completeness, "git commit -u|--update <files>" could also
>> exist but would probably be of no use.
>>
>> To sum up, "all" would be consistently expressed with the <dir> syntax.
>> "git commit -a" would not mean "--all" anymore. Lastly, a distinction
>> would be made between "--add" and "--update":
>> - "git commit -add" would have the same semantics as "git add"
>
> This is bollocks. git commit should commit things. We'll be in some
> serious trouble if "git commit -a" stops working the way it has and
> starts just adding things to index.

I agree everything you said in your response to Jerome, except for one thing.

We might want to allow:
	$ git commit untracked.c tracked.c
to internally 'git add' untracked files while making the commit.
Currently you would get:
	$ git commit untracked.c tracked.c
        error: pathspec 'untracked.c' did not match any file(s) known to git.
        Did you forget to 'git add'?

which is usable, safe, and helpful, so changing it to automatically including it would not help the end user that much and one could argue that it removes the safety which is a bad idea.

So, let's not do this; sorry for the noise.
Jerome Lovy· Dec 18, 2006, 11:48 UTC · re: Andreas Ericsson · lore

Re: [RFC] A unique way to express "all" (vs "add vs "update") ?

Hi,
Andreas Ericsson wrote:
Show 35 quoted lines
> Jerome Lovy wrote:
>> While I am very happy with the refactorings undertaken with regard to
>> "git add/git commit" (both for UI and documentation), I am still a
>> little confused by the different ways I seem to find to express the idea
>> "I want to add (sort of) all file contents".
>>
>> To be more specific, I find the following in the current documentation:
>>
>> git add <dir>
>>     "adds content from all files under <dir>  directory and its
>>     subdirectories."
>>     (as interpreted from the "EXAMPLES" section of the git-add
>>     man-page)
>>     (BTW, could this <dir> usage be documented in the SYNOPSIS and
>>     DESCRIPTION sections (admittedly at a 2nd rank after the
>>     currently documented usage)  as well as in the EXAMPLES ?
>>     Besides this reference sections would probably include the
>>     <dir>/<regexp> usage that I've not mentioned here for the sake
>>     of simplicity.)
>>         Moreover, the tutorial documents the typical usage "git add ."
>>
>> git commit -a|--all
>>     "automatically stage files that have been modified and deleted,
>>     but new files you have not told git about are not affected."
>>
>> Granted, the latter semantics for "all" is not exactly the same as the
>> former. Nonetheless, I think it would be very nice to only have to 
>> memorize one way to express "all".
>>
> 
> But the former isn't "all"; It's a specific directory, although "." 
> happens to *look* like "all", you can run "git add ." in a subdirectory 
> inside the repository and it won't mean "all" anymore. Likewise, you can 
> say "git commit ." from a subdirectory and have it commit all changes to 
> all tracked files under that directory.

OK. For my information, are the following commands completely equivalent ? 1) git commit -a 2) (cd `git-rev-parse --git-dir`/..; git commit .)

Show 27 quoted lines
> 
>> To this end, I would be very happy with the following:
>> (X-mas is coming soon, isn't it ;-)  )
>>
>> git add <dir>
>>     same semantics
>>
>> git commit -a|--add <files>
>>     "adds content from the specified files before committing
>>     (files that are already tracked have their current content
>>     staged)"
>>
>> git commit -a|--add <dir>
>>     "adds content from all files under <dir>  directory and its
>>     subdirectories before committing"
>>     (once again, for simplification of my explanations, I omit the
>>     <dir>/<regexp> usage here)
>>
>> git commit -u|--update <dir>
>>     "automatically stage files that have been modified and deleted
>>     under <dir>  directory and its subdirectories, but new files you
>>     have not told git about are not affected."
>>     (once again, for simplification of my explanations, I omit the
>>     <dir>/<regexp> usage here)
>>
> 
> But this isn't "commit" at all. It's "git add".
OK. To faithfully follow the current existing description of
'git commit -a', I should have indeed written:
git commit -u|--update <dir>
     "_Tell the command to_ automatically stage files that have been
     modified and deleted under <dir>  directory and its subdirectories,
     but new files you have not told git about are not affected."
Show 15 quoted lines
> 
>>     (This would allow the typical usage "git commit -u ." which is
>>     barely longer than the current "git commit -a")
>>
>> For interface completeness, "git commit -u|--update <files>" could also
>> exist but would probably be of no use.
>>
>> To sum up, "all" would be consistently expressed with the <dir> syntax.
>> "git commit -a" would not mean "--all" anymore. Lastly, a distinction
>> would be made between "--add" and "--update":
>> - "git commit -add" would have the same semantics as "git add"
> 
> This is bollocks. git commit should commit things. We'll be in some 
> serious trouble if "git commit -a" stops working the way it has and 
> starts just adding things to index.
OK. I obviously wasn't precise enough. Let me restate:
- "git commit -add" would allow the same <file>/<dir> parameter usage as 
"git add"
Show 8 quoted lines
> 
>> - "git commit --update" on the other hand would only affect the files
>>   already tracked
>>
> 
> I fail to see what you're after with the changes propsed in this mail.
> Is there a use-case you've encountered where you wanted to do something 
> that wasn't possible, or easy enough, that made you post this?

My case is not that I've encountered something that wasn't possible or easy enough (everything is indeed possible with the right combination of "git add" and "git commit"), but rather that I candidly felt that "--all" is more difficult to understand/learn/memorize/teach than expected since it doesn't really mean "all" (because it excludes "new files you have not told git about").

> 
> Unless it's a very, very good reason I most urgently think we're better 
> off keeping the current "git commit -a" behaviour.
>
Carl Worth· Dec 15, 2006, 23:07 UTC · re: Jerome Lovy · lore

Re: [RFC] A unique way to express "all" (vs "add vs "update") ?

On Fri, 15 Dec 2006 12:38:51 +0100, Jerome Lovy wrote:
> While I am very happy with the refactorings undertaken with regard to
> "git add/git commit" (both for UI and documentation), I am still a
> little confused by the different ways I seem to find to express the idea
> "I want to add (sort of) all file contents".

I agree that there have been huge improvements---particularly in documentation. So thanks to everybody!

Here's a simpler idea that might add the unification you're looking for. How about a new option:

	git add -a|--all

This would allow "git commit -a|--all" to be understood as a simple helper for:

	git add -a|--all
	git commit

That kind of unification seems like it could be helpful while learning things. And I believe I've even wanted to do the "git add -a" operation before, so I think it might be useful in its own right at times, (though I can't think of a good example of why at the moment, so perhaps its not that important).

-Carl
Jerome Lovy· Dec 18, 2006, 14:04 UTC · re: Carl Worth · lore

Re: [RFC] A unique way to express "all" (vs "add vs "update") ?

Carl Worth wrote:
Show 22 quoted lines
> On Fri, 15 Dec 2006 12:38:51 +0100, Jerome Lovy wrote:
>> While I am very happy with the refactorings undertaken with regard to
>> "git add/git commit" (both for UI and documentation), I am still a
>> little confused by the different ways I seem to find to express the idea
>> "I want to add (sort of) all file contents".
> 
> I agree that there have been huge improvements---particularly in
> documentation. So thanks to everybody!
> 
> Here's a simpler idea that might add the unification you're looking
> for. How about a new option:
> 
> 	git add -a|--all
> 
> This would allow "git commit -a|--all" to be understood as a simple
> helper for:
> 
> 	git add -a|--all
> 	git commit
> 
> That kind of unification seems like it could be helpful while learning
> things.
Exactly. I like it.

Now, it underlines the fact that this "--all" should IMHO rather be called "--all-known" or the like - both for "add" and "commit" - but all the same, I would be very happy with a more complete "git add" following your proposed unification.

Jérôme

← back to recent threads