Documentation/howto/using-topic-branches.txt

   1 Date: Mon, 15 Aug 2005 12:17:41 -0700
   2 From: tony.luck@intel.com
   3 Subject: Some tutorial text (was git/cogito workshop/bof at linuxconf au?)
   4
   5 Here's something that I've been putting together on how I'm using
   6 GIT as a Linux subsystem maintainer.
   7
   8 I suspect that I'm a bit slap-happy with the "git checkout" commands in
   9 the examples below, and perhaps missing some of the _true-git_ ways of
  10 doing things.
  11
  12 -Tony
  13
  14 Linux subsystem maintenance using GIT
  15 -------------------------------------
  16
  17 My requirements here are to be able to create two public trees:
  18
  19 1) A "test" tree into which patches are initially placed so that they
  20 can get some exposure when integrated with other ongoing development.
  21 This tree is available to Andrew for pulling into -mm whenever he wants.
  22
  23 2) A "release" tree into which tested patches are moved for final
  24 sanity checking, and as a vehicle to send them upstream to Linus
  25 (by sending him a "please pull" request.)
  26
  27 Note that the period of time that each patch spends in the "test" tree
  28 is dependent on the complexity of the change.  Since GIT does not support
  29 cherry picking, it is not practical to simply apply all patches to the
  30 test tree and then pull to the release tree as that would leave trivial
  31 patches blocked in the test tree waiting for complex changes to accumulate
  32 enough test time to graduate.
  33
  34 Back in the BitKeeper days I achieved this my creating small forests of
  35 temporary trees, one tree for each logical grouping of patches, and then
  36 pulling changes from these trees first to the test tree, and then to the
  37 release tree.  At first I replicated this in GIT, but then I realised
  38 that I could so this far more efficiently using branches inside a single
  39 GIT repository.
  40
  41 So here is the step-by-step guide how this all works for me.
  42
  43 First create your work tree by cloning Linus's public tree:
  44
  45  $ git clone rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work
  46
  47 Change directory into the cloned tree you just created
  48
  49  $ cd work
  50
  51 Make a GIT branch named "linus", and rename the "origin" branch as linus too:
  52
  53  $ git checkout -b linus
  54  $ mv .git/branches/origin .git/branches/linus
  55
  56 The "linus" branch will be used to track the upstream kernel.  To update it,
  57 you simply run:
  58
  59  $ git checkout linus && git pull linus
  60
  61 you can do this frequently (as long as you don't have any uncommited work
  62 in your tree).
  63
  64 If you need to keep track of other public trees, you can add branches for
  65 them too:
  66
  67  $ git checkout -b another linus
  68  $ echo URL-for-another-public-tree > .git/branches/another
  69
  70 Now create the branches in which you are going to work, these start
  71 out at the current tip of the linus branch.
  72
  73  $ git checkout -b test linus
  74  $ git checkout -b release linus
  75
  76 These can be easily kept up to date by merging from the "linus" branch:
  77
  78  $ git checkout test && git resolve test linus "Auto-update from upstream"
  79  $ git checkout release && git resolve release linus "Auto-update from upstream"
  80
  81 Set up so that you can push upstream to your public tree:
  82
  83  $ echo master.kernel.org:/ftp/pub/scm/linux/kernel/git/aegl/linux-2.6.git > .git/branches/origin
  84
  85 and then push each of the test and release branches using:
  86
  87  $ git push origin test
  88 and
  89  $ git push origin release
  90
  91 Now to apply some patches from the community.  Think of a short
  92 snappy name for a branch to hold this patch (or related group of
  93 patches), and create a new branch from the current tip of the
  94 linus branch:
  95
  96  $ git checkout -b speed-up-spinlocks linus
  97
  98 Now you apply the patch(es), run some tests, and commit the change(s).  If
  99 the patch is a multi-part series, then you should apply each as a separate
 100 commit to this branch.
 101
 102  $ ... patch ... test  ... commit [ ... patch ... test ... commit ]*
 103
 104 When you are happy with the state of this change, you can pull it into the
 105 "test" branch in preparation to make it public:
 106
 107  $ git checkout test && git resolve test speed-up-spinlocks "Pull speed-up-spinlock changes"
 108
 109 It is unlikely that you would have any conflicts here ... but you might if you
 110 spent a while on this step and had also pulled new versions from upstream.
 111
 112 Some time later when enough time has passed and testing done, you can pull the
 113 same branch into the "release" tree ready to go upstream.  This is where you
 114 see the value of keeping each patch (or patch series) in its own branch.  It
 115 means that the patches can be moved into the "release" tree in any order.
 116
 117  $ git checkout release && git resolve release speed-up-spinlocks "Pull speed-up-spinlock changes"
 118
 119 After a while, you will have a number of branches, and despite the
 120 well chosen names you picked for each of them, you may forget what
 121 they are for, or what status they are in.  To get a reminder of what
 122 changes are in a specific branch, use:
 123
 124  $ git-whatchanged branchname ^linus | git-shortlog
 125
 126 To see whether it has already been merged into the test or release branches
 127 use:
 128
 129  $ git-rev-list branchname ^test
 130 or
 131  $ git-rev-list branchname ^release
 132
 133 [If this branch has not yet been merged you will see a set of SHA1 values
 134 for the commits, if it has been merged, then there will be no output]
 135
 136 Once a patch completes the great cycle (moving from test to release, then
 137 pulled by Linus, and finally coming back into your local "linus" branch)
 138 the branch for this change is no longer needed.  You detect this when the
 139 output from:
 140
 141  $ git-rev-list branchname ^linus
 142
 143 is empty.  At this point the branch can be deleted:
 144
 145  $ rm .git/refs/heads/branchname
 146
 147 To create diffstat and shortlog summaries of changes to include in a "please
 148 pull" request to Linus you can use:
 149
 150  $ git-whatchanged -p release ^linus | diffstat -p1
 151 and
 152  $ git-whatchanged release ^linus | git-shortlog
 153