Re: git patch

[Graham Percival]

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


MERGE PROBLEM

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
Nope.
Merging HEAD with c21d3f3e1c77722e50d994763442e6f994b03ac2
Merging:
038b7fc Misc small updates (trying to make git work).
c21d3f3 Merge branch 'master' of 
ssh+git://address@hidden/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://address@hidden/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" 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
}

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.

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