Subject: git newbie problems

From: Graham Percival <[email-masked]>
Date: Tue, 05 Dec 2006 16:41:29 -0800

Greetings,

I'm posting these problems at Han-Wen and Dscho's insistence.  I'm the 
documentation editor for GNU/LilyPond, so I'm reluctant to criticize 
other project's documentation unless I spend an hour or more seriously 
reading it.  I'm quite willing to admit that 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.  By "make 
things work", I mean imitating my work style with cvs:

cvs co blah blah  (which I simply copy and paste from savannah)
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 my changes.
   cvs ci foo/bar/baz.txt  // upload changes
}

Once or twice a year I'll do "cvs diff" or "cvs add", 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.  (note that I was reading the 
"tutorial introduction to git")

I should add that I've received help on the lilypond-devel list; I'm 
posting this in case it helps future development for git docs, not 
because I need more help to use git.

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.

MERGE PROBLEM

Two people (me and another person) edited the same line on
Documentation/user/advanced.itely at the same time.  (note that this 
file has existed for over a year; it's not a new file)  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
Nope.
Merging HEAD with c21d3f3e1c77722e50d994763442e6f994b03ac2
Merging:
038b7fc Misc small updates (trying to make git work).
c21d3f3 Merge branch 'master' of
ssh+git://[email-masked]/srv/git/lilypond
found 1 common ancestor(s):
84219bb don't have input/templates/ any longer.
fatal: Entry '.gitignore' would be overwritten by merge. Cannot merge.
No merge strategy handled the merge.

As a git newbie, I'm quite confused.  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.  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'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.
Nope.
Merging HEAD with c21d3f3e1c77722e50d994763442e6f994b03ac2
Merging:
038b7fc Misc small updates (trying to make git work).
c21d3f3 Merge branch 'master' of
ssh+git://[email-masked]/srv/git/lilypond
found 1 common ancestor(s):
84219bb don't have input/templates/ any longer.
fatal: Entry '.gitignore' would be overwritten by merge. Cannot merge.
No merge strategy handled the merge.

Now I'm totally confused, because I definitely haven't touched .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.

It would be nice to have an accompanying "tutorial introduction to
contributing with git" for users (like me) who are not in control of a 
project.

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

Cheers,
- Graham Percival