git newbie problems

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://hanwen@git.sv.gnu.org/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://hanwen@git.sv.gnu.org/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