Re: git patch

[Johannes Schindelin]

Hi,

On Tue, 5 Dec 2006, Graham Percival wrote:

> Han-Wen Nienhuys wrote:
> > This is interesting. There has been lots of discussion on the git mailing
> > list, about git being hard to understand, but -it being a developer's list-
> > little data from actual newbie users. Could you take some brief notes about
> > what tripped you up, and post them?
> 
> I'm reluctant to post to the git mailing list because I'm completely willing
> to admit that this is probably a stupid luser problem.  I never seriously
> tried to read the docs on the overall theory of git (branches, repo, etc); I
> just flailed around looking for magic commands to make things work.

I would like to post your mail (anonymized, of course) to the git list. 
May I? I am on this list since a long time, and there has _never_ been an 
occasion where a newbie was punished for asking, so maybe you want to post 
them yourselves, to make them understand what the problems are if you 
_not_ happen to know git pretty well.

> I suppose I _could_ blame git docs for not making these commands more 
> obvious... but I'm really not keen on criticizing documentation unless 
> I've actually read it seriously.  The only times I've seriously 
> considered stopping involvement with lilypond have been when people ask 
> obvious RTFM questions.
> 
> This case was particularly difficult because the very first time I tried 
> to commit... err... push... err... "make my doc changes available to 
> everybody else" (whatever the right term is), there was this merge 
> problem.

Hmm. Yes. It would be a pretty good idea, I think, to tell _everybody_ 
that "git pull" is _the_ equivalent to "cvs update". So, if you cloned 
your local git repository with "git clone" from the upstream, you can 
merge the upstream repository with "git pull".

> Two people (me and Mats) edited the same line on
> Documentation/user/advanced.itely at the same time.  When I tried to get the
> most recent changes, I'm greeted with this:
> ...
> Trying really trivial in-index merge...
> Documentation/user/advanced-notation.itely: needs merge
> fatal: you need to resolve your current index first

This is really obscure, you're right. What Git means: 
advanced-notation.itely was not committed yet.

With Git, branches really are a serious tool. Even if Mats and you thought 
you were working on the same branch, you really were not! Just by using 
git, you already had your own private branch.

So, before trying to merge your work with Mats' work, you _have_ to commit 
your changes! This was impossible with CVS, since CVS basically allows 
only linear development and makes anything else _hard_.

So, first commit your changes, _then_ merge other's work.

What might help you in such cases: "git status". It tells you which files 
were modified, and which files are untracked, i.e. not versioned.

> fatal: Entry '.gitignore' would be overwritten by merge. Cannot merge.

If I'm correct, this means that you have a file named ".gitignore" in your 
working directory, which is either not versioned yet, or modified.

Again, you can just commit it (if it is not already in the repository, you 
will need to add it with "git add .gitignore"), and _then_ merge your 
work.

> As a git newbie, I'm quite confused.

Fair enough. Git does not really tell you what is happening... Note that 
there are quite a number of efforts going on on the Git list to make Git 
less intimidating to new users...

> OK, there's no merge strategy... so what do I do now?  With cvs, the 
> changes would be dumped into the file.  I look at the file, found the 
> conflict, and tried it again.

When you find the conflict, you should fix it, and then do a

$ git commit -a

to commit your merge. In general, "git commit" needs a list of files to be 
committed, but as a short cut you can pass "-a" to say "all modified 
files you know about".

> I got the same error message, and then it occurred to me that although I 
> changed the files in my ~/usr/src/lilypond, git might be storing these 
> files somewhere else.  So I tried
> 
> $ git commit Documentation/user/advanced-notation.itely
> Cannot do a partial commit during a merge.
> You might have meant to say 'git commit -i paths...', perhaps?
> 
> ... eh?

I am guessing that .gitignore hurts here. It said that it did not want to 
just overwrite that file.

> I'm trying to fix this so that you _can_ merge!  Regardless, when I
> tried to update again, I get
> 
> $ git pull gnu master
> ...
> Trying really trivial in-index merge...
> fatal: Entry '.gitignore' would be overwritten by merge. Cannot merge.

So, maybe .gitignore really is not versioned? You can see that by looking 
through the output of "git status".

> Now I'm totally confused, because I definitely haven't touched 
> .gitignore.

Please do "git status" to see what is happening to .gitignore.

> SUGGESTIONS
> 
> The "tutorial introduction to git" looks like a nice document, but it 
> assumes that you are in control of the project.  For users who aren't in 
> control (ie me) this is a problem, because it starts me skimming. 
> "Importing a project"... nah, that's not me.  "Merging branches"... I 
> don't care; I'm going to shove everything into the main branch.  "Using 
> git for collaboration"... hmm, maybe this is the stuff I need to read. 
> But by this point, I've already skimmed through five screens of info, so 
> I'm not reading very carefully.

That is exactly what I was expecting when I saw that lengthy tutorial, 
which really does not teach you what Git is about, but rather, how to use 
it as a maintainer.

Please do speak up on the Git list: they _need_ to know why Git is so 
hard. They will reluctantly, but eventually, realize why.

> It would be nice to have an accompanying "tutorial introduction to 
> contributing with git" that just goes over the following steps (in their 
> git equivalent):
> 
> 
> cvs co blah blah  (which I simply copy and paste from savannah anyway)
> while (true) {
>   cvs update          // get changes that happened overnight
>   vi foo/bar/baz.txt  // or whatever editing commands you do
>   make; make web      // or whatever testing commands you do
>   cvs update          // get latest changes to prepare for
>                       // uploading changes.  This step may or
>                       // may not be required in git.
>   cvs ci foo/bar/baz.txt  // upload changes
> }

I try to translate:

$ git clone blah blah
$ while (true) {
$    git pull      # get latest changes; you must have a clean working dir
$    vi foo/bar/baz.txt
$    make; make web
$    git commit -a # you will be prompted for a meaningful message
$ # alternatively: git commit foo/bar/baz.txt
$ }

> 
> Once or twice a year I'll do "cvs diff", but all I really want are the 
> above commands.  I figured that this should be really easy to do, so I 
> kept on skimming through the docs, trying to find the equivalent of 
> these really easy commands.

I hope I helped here.

> Finally, it would be really nice if there was some mention of "resolving 
> merge problems" in the tutorial (both in the current one and any new 
> docs).

Basically, if you have a merge problem, you either did not commit, or you 
got conflicts. The former can be helped by committing your changes, the 
latter by editing the files with conflict markers, and after fixing those 
issuing "git commit -a".

That (what to do when a merge fails) might be the next thing I put on the 
Git Wiki (git.or.cz).

Hth,
Dscho