threads / discuss / 28064

Suggestions to make git easier to understand

Subject: Suggestions to make git easier to understand

## tl;dr

6 messages between Aug 11, 2011 and Aug 15, 2011.

replies: 5people: 4as markdown or json

Philippe Vaucher· Aug 11, 2011, 07:48 UTC · lore

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.

Jonathan Nieder· Aug 11, 2011, 22:16 UTC · re: Philippe Vaucher · lore

Re: Suggestions to make git easier to understand

Hi Philippe,

Philippe Vaucher wrote:

Show 5 quoted lines

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

Show 9 quoted lines

> 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

Junio C Hamano· Aug 11, 2011, 22:39 UTC · re: Jonathan Nieder · lore

Re: Suggestions to make git easier to understand

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 11 quoted lines

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

Jonathan Nieder· Aug 11, 2011, 23:08 UTC · re: Junio C Hamano · lore

Re: Suggestions to make git easier to understand

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

Jeff King· Aug 12, 2011, 22:26 UTC · re: Jonathan Nieder · lore

Re: Suggestions to make git easier to understand

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

Show 9 quoted lines

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

Philippe Vaucher· Aug 15, 2011, 10:15 UTC · re: Jeff King · lore

Re: Suggestions to make git easier to understand

> 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