Git Contributors Guide (Was: Re: destructor order)

[Ulrik Mikaelsson]

2011/1/26 Steven Schveighoffer <schveiguy at yahoo.com>:
>> Steve, if you could point out what I need to do I'll be glad to do it
>> right now. Better yet, feel free to try your hand at a git commit. It's fun!
> *sweats nervously* I don't know, I'd like to read about how git works before
> doing a commit.  I don't really understand it at all, I had the same problem
> with subversion when I started using it.

This seems like a good time for a quick git-contributors guide. There
are plenty of guides in other places, but anyways; (this is for Linux
and the native Git). I do not know about how to work with other
versions such as Tortoise, or on other platforms, but it should be
very similar.

One-time thing for first-time git; tell git who you are:
  $ git config --global user.name "John Doe"
  $ git config --global user.email "john.doe at server.com"

1. Clone out a fresh copy of the project from github, i.e.
  $ git clone git://github.com/D-Programming-Language/druntime.git
2. Do your thing. Change whatever file you need.
3. Stage your changes with "git add <file>" for any added or changed file.
  $ git add "path/myfile"
4. Commit with "git commit". Your editor will pop up asking for a
commit-message.
  $ git commit

** Short-path **: If there are no _new_ files in the commit, you can
skip step 3, and "git commit -a" without the "git add"-stage. This
will make the commit-command work like in Subversion.
** GUI-alternative **: For step 3 and 4, please try out the excellent
"git gui" command, which let's you pick individual lines in files to
commit. Great for splitting up work into logical patches. Also has
support for amending the last patch in line, fixing typos and such.

Your commit is now done. You can examine it with the command "git log"
which will show you the commit-history, and "git show", which will
show you the last commit in detail.
** GUI-alternative **: I find "gitk" to be immensely useful to review
things before submitting or publishing them. It allows all sorts of
niceties, reviewing both changes and snapshotted trees from history,
comparing revisions and following changes to a single file.

There are now many ways to now submit the patch.
 The BEST way is probably publishing your branch in some public place
like github, and send a notification to the respective mailing-list,
or bug-tracker. It is described at github itself.
 Another way is of course generating a plain old git diff, but that
does not retain authorship or time. Nor is it practical for series of
patches.
The way I will show here is to gather up your changes in a so-called
"bundle", which can then be sent by mail or attached in a bug-tracker.
First, some terms that might need explaining.
  :origin: A repository usually has "neighboring" repositories, friend
whom you often communicate with. "origin" is the default-name of the
repository you originally cloned. "upstream" so to speak.
  :master: In each repository, there can be many branches. "master" is
by default the name of the "trunk", in SVN-terms.

So, when one speaks about "origin/master", one is basically saying
"trunk of upstream". Now, creating your bundle is as simple as:
 $ git bundle create mypatch.gitbundle origin/master..   # Dont forget
the double-dots.
This tells git to bundle up all revisions on my current branch, that
aren't in "upstream". This will generate the file "mypatch.gitbundle",
which can be sent to for review.

The reviewer then "pulls" from it by:
 $ git checkout -b review                # Create new review-branch.
 $ git pull <path/to/bundle> HEAD   # Import from bundle.
The changes will now be merged into the reviewers tree, in a special
review-branch, where verification can be made, tests can be run and,
possibly small fixes to the patch can be appended. When done, change
to master-branch and merge the changes (if they are acceptable).
 $ git checkout master                  # Checkout the master-branch
(or some other branch if integration should happen there instead)
 $ git merge review                      # Merge in the review-branch
 $ git branch -d review                  # And drop it

Hope this helps. For more advanced, and continual work, you should
probably setup a private fork, described at
http://help.github.com/forking/.

Happy Git:ing!