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

From: Andreas Ericsson <[email-masked]>
Date: Fri, 15 Dec 2006 13:09:14 +0100

Jerome Lovy wrote:
> 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.

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

>     (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                   [email-masked]
OP5 AB                             www.op5.se