Suggestions to make git easier to understand

Suggestions to make git easier to understand

[Philippe Vaucher]

Hello,

The other day I fell on this post:

http://raflabs.com/blogs/silence-is-foo/2011/04/07/staging-area-index-cache-git/

I thought it made some good points about git being kinda confusing,
for example sentences like "Changed but not updated" in git status
could use a better sentence like "Changed but not in the index". Maybe
--cached could have an alias like --index-only for things to be more
intuitive as well.

`git rm --index-only somefile` is more understandable than `git rm
--cached somefile` imho.

Also, in ls-files, --stage could maybe use an alias like --contents
for it to be more self-explanatory.

Philippe

p.s: not saying we should absolutly do what I suggest, but rather
start a discussion about how to make git's terminology more intuitive
and self-explanatory.

Re: Suggestions to make git easier to understand

[Jonathan Nieder]

Hi Philippe,

Philippe Vaucher wrote:

> http://raflabs.com/blogs/silence-is-foo/2011/04/07/staging-area-index-cache-git/
>
> I thought it made some good points about git being kinda confusing,
> for example sentences like "Changed but not updated" in git status
> could use a better sentence like "Changed but not in the index".

Sounds reasonable (well, with some more precise wording to reflect
that this means "changed but not all changes are reflected in the
index").

> Maybe
> --cached could have an alias like --index-only for things to be more
> intuitive as well.
> 
> `git rm --index-only somefile` is more understandable than `git rm
> --cached somefile` imho.
> 
> Also, in ls-files, --stage could maybe use an alias like --contents
> for it to be more self-explanatory.

These suggestions also seem sane.  Please send patches
(Documentation/SubmittingPatches explains how) so we can refine them
and fix this.

Thanks much,
Jonathan

Re: Suggestions to make git easier to understand

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

>> Maybe
>> --cached could have an alias like --index-only for things to be more
>> intuitive as well.
>> 
>> `git rm --index-only somefile` is more understandable than `git rm
>> --cached somefile` imho.
>> 
>> Also, in ls-files, --stage could maybe use an alias like --contents
>> for it to be more self-explanatory.
>
> These suggestions also seem sane.

The --index-only synonym was throwed around in a handful of discussions in
the past. It probably would not hurt, I would say.

I do not think "ls-files --contents" makes things any better, though.
Until a new user encounters a conflicted state, it might look like that
the primary point of "ls-files -s" is to show the object names, but it
also is important that it shows the stage numbers.

Re: Suggestions to make git easier to understand

[Jonathan Nieder]

Junio C Hamano wrote:

> I do not think "ls-files --contents" makes things any better, though.
> Until a new user encounters a conflicted state, it might look like that
> the primary point of "ls-files -s" is to show the object names, but it
> also is important that it shows the stage numbers.

Yes, sloppy of me.  I should have said "the intent of these
suggestions seems reasonable, and I believe that with minimal tweaking
they would all lead to good things".

In the case of "ls-files -s", I suspect what would be most useful is
a new porcelain "git ls --merge", building on Duy's work[*].

[*] http://thread.gmane.org/gmane.comp.version-control.git/166405/focus=166415

Re: Suggestions to make git easier to understand

[Jeff King]

On Thu, Aug 11, 2011 at 05:16:27PM -0500, Jonathan Nieder wrote:

> > http://raflabs.com/blogs/silence-is-foo/2011/04/07/staging-area-index-cache-git/
> >
> > I thought it made some good points about git being kinda confusing,
> > for example sentences like "Changed but not updated" in git status
> > could use a better sentence like "Changed but not in the index".
> 
> Sounds reasonable (well, with some more precise wording to reflect
> that this means "changed but not all changes are reflected in the
> index").

Didn't we fix this already in 8009d83 (Better "Changed but not updated"
message in git-status, 2010-11-02)? Since v1.7.4, "git status" has
"Changes not staged for commit".

-Peff

Re: Suggestions to make git easier to understand

[Philippe Vaucher]

> Didn't we fix this already in 8009d83 (Better "Changed but not updated"
> message in git-status, 2010-11-02)? Since v1.7.4, "git status" has
> "Changes not staged for commit".

Yes, and the new text is fine for me.

Philippe