git guidelines for gnulib: topic branches

[Jim Meyering]

Here's a preliminary draft.
If you go through it, please tell me about anything
that seems confusing, pointless, etc.
Eventually I'll merge into it some of the things mentioned
in http://thread.gmane.org/gmane.comp.lib.gnulib.bugs/11266/focus=11268.

Jim
-------------------------------------------------------------------------
For projects using GIT where I can "push" changes to a public repository,
here is how I like to work:

Big picture, for each self-contained change:

    I make changes on a local-only (private) temporary branch, BR.
    This is sometimes called a topic branch in git documentation.
    Changes on this sort of branch are not published when you
    run "git-push".

    I am free to commit incomplete and non-functional code, since
    this is a private work in progress.

    I can update the trunk from the shared repo whenever I want,
    without having to worry about conflicts with my work in progress.

    I can rebase my local changes so they would "fit" on the trunk (this
    is where I may have to deal with conflicts) whenever it's convenient
    for me.

    When this change is ready to be published, I pull the contents of
    BR onto the trunk (aka master) and push master to the public repository.
    Then, since I've just copied all of BR onto the trunk,
    I remove that temporary branch.

Details:

    git-clone git://git.sv.gnu.org/gnulib && cd gnulib

    # create temporary branch BR, off of master, and check it out:
    git-checkout -b BR

    # Now, right after you've created the branch, switching back to
    # the trunk doesn't change any of your files.  Use "git-branch"
    # to see which branch you're on:

        $ git-branch
        * BR
          master

    # The name marked with "*" is the current branch.
    # Just for demonstration purposes, checkout the trunk via
    # "git-checkout master", rerun git-branch, then get back on BR:

        $ git-branch
          BR
        * master
        $ git-checkout BR

    # Getting back to the business of developing changes on your branch:
    # ... make changes and commit ...
    git-commit
    # ... repeat, as desired.  These deltas go on branch BR.
    git-commit

    # Pull others' new work onto local trunk (aka master).
    # It's best (but not always necessary) to have committed any work in
    # progress to BR before doing the following.  If you forget and end
    # up with a merge and conflicts, it can be a pain.
    git-checkout master && git-pull && git-checkout BR

    # The above pulls changes from the shared repo into your repo's trunk,
    # but does not affect your WIP on BR.  When you want to combine your
    # changes on BR and those on "master", use "git-rebase".

    # The following presumes you're "on" the branch, BR.
    # To confirm that, run git-branch:

        $ git-branch
        * BR
          master

    # Now, to make it so that all of your changes along the BR branch
    # apply perfectly to the new "master", you do this:

    git-rebase master

    # If you're lucky, that will simply succeed, and you're done.
    # Otherwise, you'll see notification of conflicts, each of which
    # you have to resolve.  For each file with now-resolved conflicts
    # you then have to tell git-rebase that you really have resolved
    # them (say in files F1 and F2) by running e.g., git-add F1 F2.
    # Then you can say "git-rebase --continue" to have it take up where
    # it left off.
    # But don't worry.  If you forget the "git-add ..." step, when you
    # run "git-rebase --continue", it will notice and tell you what to do.

    # Now, you can continue committing changes to this local branch,
    # and pulling-trunk/rebasing whenever you want.

    ################################################################
    # A word of caution:
    # Changing from one branch to another is so easy, quick, and
    # quiet (especially if you're used to CVS or svn) that it's easy
    # to forget that a simple "git-checkout master" or "git-checkout BR"
    # can make massive changes to your working directory -- it all
    # depends solely on how many files differ between your BR and
    # the trunk.

    ################################################################
    # Publishing the work from your private branch
    #
    # Here's what to do when you're ready to "publish" your work by
    # putting it on the trunk and pushing to the shared repository:

    # First, make sure you have no uncommitted deltas.
    # This diff should produce no output:
    git-diff

    # Checkout the trunk and pull the latest:
    git-checkout master && git-pull

        # If the above "pull" changed anything, do another rebase,
        # resolve any conflicts and return to the trunk:
        git-checkout BR && git-rebase master
        [...and resolve any conflicts...]
        git-checkout master

    # Finally, now that you're on the trunk (which is up to date
    # with the public repo), pull your BR changes onto the trunk
    # and push the result to the shared repository:
    git-pull . BR
    git-push

    # Finally, it's good to clean up by removing that temporary
    # branch, since a copy is now on the trunk and published.
    git-branch -d BR

    ################################################################
    # Miscellaneous useful commands, in addition to well-known ones
    # like "git-diff":
    #
      * gitk: give a graphical view of the revision graph
      * git-log: to get most of the same info in text form
      * git-log -p: same as above, but with diffs
      * git-log -p SOME_FILE: same as above, but limit to SOME_FILE
      * git-reset --soft HEAD^: Commit the delta required to restore
          state to the revision just before HEAD (i.e., next-to-last).

    # As integrators, you'll have to tell people how you'd like them
    # to submit patches.  Here's one way, assuming they create a single
    # change set:

      * git-format-patch --stdout --signoff HEAD~1 > DIFF
          Produce a patch (the most recent commit) suitable for application
          by you or someone else using "git-am".  This is useful when you
          cannot push the patch yourself.  You commit locally and run this,
          then send the output ("DIFF") to the person who will push.
          What will they do?

             Create temp branch, and checkout, as above.
             Apply your patch on that temp branch: run "git-am DIFF"
             Make any additional changes, committing them either with
               a separate commit or with git-commit -e --amend (do this
               only if your addition is really small, and you're really
               confident that your change won't break theirs, because
               it'll still have their name on it, with no indication of
               which part you've changed).
             Eventually, pull that branch onto the trunk and publish.