Re: VC mode and git

[Eli Zaretskii <eliz@gnu.org>]

> Date: Mon, 06 Apr 2015 16:58:09 +0200
> From: martin rudalics <rudalics@gmx.at>
> CC: emacs-devel@gnu.org
> 
> A few further comments on the last version of GitQuickStartForEmacsDevs:

Thanks.

>    Optionally, before doing a commit, you can do git status and git diff to
>    view the changes which will be committed by git commit -a (with no
>    filename arguments).
> 
> Couldn't we formulate this in a slightly more appealing way?

I tried to do that, please take another look.

>    It is a good idea to examine what you are about to push, before
>    actually doing so, because fixing mistakes before pushing is much
>    easier (see the next section). To do that, use the command git diff
>    origin/master. If you want to show your unpushed commits with their
>    commit log messages, use git show origin/master.. instead. If you only
>    have one local commit you want to push, just git show is enough.
> 
> And here I would try to tell that the outputs of plain 'git diff' and
> 'git status' are different from their outputs before the commit.

In the new version, "git diff" is no longer mentioned, and "git
status" was never mentioned before, so do you still think we need to
say something about that?

>    To re-do the commit from scratch, use git reset HEAD^, then fix
>    whatever needs fixing, and commit again.
> 
> Maybe we should reassure readers here that their changes are not lost
> when they do that.

Done.

>    error: Your local changes to the following files would be overwritten by merge:
>           file1
>    Please, commit your changes or stash them before you can merge.
>    Aborting
> 
>    To fix this, commit the offending files with
> 
> Please tell readers here that git does not even try to check whether
> their changes would conflict with changes in the upstream repository.
> Otherwise, the cited section will confuse readers who expect conflicts
> exclusively due to the earlier ...
> 
>    This merge could fail due to conflicts between your changes and
>    changes by others in the same portions of the same files.
> 
> ... in particular the "in the same portions" part.  At least I was
> initially stupefied by this when it happened the first time.

But the full text says this:

  This merge could fail due to conflicts between your changes and
  changes by others in the same portions of the same files. The
  conflicts could be in changes you have already committed locally, or
  in uncommitted changes.

The second sentence refers to uncommitted changes.  Is it really
important to tell that in this case Git will not even start a merge?
How will that help the reader/user when they are in this situation?

>    In addition, saving any file whose conflicts were completely resolved
>    (i.e., no conflict markers remain in it) invokes the git add command
>    on that file, which prepares the file for merging and committing.
> 
> Are we really 100% sure that 'git add' gets executed with all reasonable
> user customizations?

As long as they didn't remove the Git back-end from the list, yes.

> Shouldn't we tell here how our reader can check whether the 'git
> add' was really performed?

Sounds excessive to me.

>     (It is recommended to do a git status before a commit without
>     filename arguments to check for inadvertent changes that would be
>     committed.)
> 
> Doesn't this come now a bit late in the text given you latest changes?

Deleted.

Thanks.