GIT

   1 =========================== WHY USE GIT+TOPGIT? ==========================
   2
   3 Three major concerns were on our mind when setting up this project.
   4
   5   o First we needed to structure the project in such a way that it would be
   6     easy to rebase all of our changes on the latest official ZFS release
   7     from Sun.  We absolutely need to be able to benefit from the upstream
   8     improvements and not get locked in to an old version of the code base.
   9
  10   o Secondly, we wanted to be able to easily manage our changes in terms
  11     of a patch stack or graph.  This allows us to easily isolate specific
  12     changes and push them upstream for inclusion.  It also allows us to
  13     easily update or drop specific changes based on what occurs upstream.
  14
  15   o Thirdly we needed our DVCS to be integrated with the management of this
  16     patch stack or graph.  We have tried other methods in the past such as
  17     SVN+Quilt but have found managing the patch stack becomes cumbersome.
  18     By using Git+TopGit to more tightly integrate our patches in to the repo
  19     we expect several benefits.  One of the most important will be the
  20     ability to easily work on the patch's with a distributed development
  21     team, additionally the repo can track patch history, and we can utilize
  22     Git to merge patches and resolve conflicts.
  23
  24 TopGit is designed to specifically address these concerns by providing
  25 tools to simplify the handling of large numbers of interdependent topic
  26 branches.  When using a TopGit aware repo every topic branch represents
  27 a 'patch' and that branch references its dependent branches.  The union
  28 of all these branches is your final source base.
  29
  30 ========================= SETTING UP GIT+TOPGIT ==========================
  31
  32 First off you need to install a Git package on your system.  For my
  33 purposes I have been working on a RHEL5 system with git version 1.5.4.5
  34 installed and it has been working well.  You will also need to go get
  35 the latest version of TopGit which likely is not packaged nicely so you
  36 will need to build it from source.  You can use Git to clone TopGit
  37 from the official site here and your all set:
  38
  39         > git clone git://repo.or.cz/topgit.git
  40         > make
  41         > make install    # Default installs to $(HOME)
  42
  43 ========================== TOPGIT AND ZFS ================================
  44
  45 One you have Git and TopGit installed you will want to clone a copy of
  46 the Linux ZFS repo.  While this project does not yet have a public home
  47 it hopefully will some day.  In the meanwhile if you have VPN access to
  48 LLNL you can clone the latest official repo here.  Cloning a TopGit
  49 controlled repo is very similar to cloning a normal Git repo, but you
  50 need to remember to use 'tg remote' to populate all topic branches.
  51
  52         > git clone git://eris.llnl.gov/zfs.git
  53         > cd zfs
  54         > tg remote --populate origin
  55
  56 Alternately, if you don't want to worry about using TopGit on your system
  57 you can simply clone the repo and then checkout the origin/top branch.  At
  58 this point you can simply create a new branch to track your changes.  You
  59 can then feed your patch back to the official repo maintainers to be merged
  60 in to the proper topic branches.
  61
  62         > git clone git://eris.llnl.gov/zfs.git
  63         > cd zfs
  64         > git checkout origin/top
  65         > git checkout -b <new_branch_name>
  66
  67 Now that you have the Linux ZFS repo the first thing you will probably
  68 want to do is have a look at all the topic branches.  TopGit provides
  69 a summary command which shows all the branches and a brief summary for
  70 each branch obtained from the .topmsg files.
  71
  72         > tg summary
  73  0      feature-branch                  [PATCH] feature-branch
  74         feature-commit-cb               [PATCH] feature commit cb
  75         feature-zap-cursor-to-key       [PATCH] feature zap cursor to key
  76         ...
  77
  78 By convention all TopGit branches are usually prefixed with 't/', however
  79 I have chosen not to do this for simplicity.  A different convention I have
  80 adopted is to tag the top most TopGit branch as 'top' for easy reference.
  81 This provides a consistent label to be used when you need to reference the
  82 branch which contains the union of all topic branches.
  83
  84 One thing you may also notice about the 'tg summary' command is it does
  85 not show the branches in dependent order.  This is done because TopGit allows
  86 each branch to express multiple dependencies as a DAC.  Initially this seemed
  87 like an added complication which I planned to avoid by just implementing a
  88 stack using the graph.   However, this ended up being problematic because
  89 with a stack when a change was made to a branch near the base, it was a
  90 very expensive operation to merge the change up to the top of the stack.
  91 By defining the dependencies as a graph it is possible to keep the depth
  92 much shallower thus minimizing the merging.  It has also proved insightful
  93 as to each patches actual dependencies.
  94
  95 To see the dependencies you will need to use the --graphviz option and pipe
  96 the result to dot for display.  The following command works fairly well for
  97 me.  Longer term it would be nice to update this option to use a preferred
  98 config options stored in the repo.
  99
 100         > tg summary --graphviz | dot -Txlib -Nfontsize=8
 101
 102 ========================= UPDATING A TOPIC BRANCH ========================
 103
 104 Updating a topic branch in TopGit is a pretty straight forward but there
 105 are a few rules you need to be aware of.  The basic process involves
 106 checking out the relevant topic branch where the changes need to be made,
 107 making the changes, committing the changes to the branch and then merging
 108 those changes in to dependent branches.  TopGit provides some tools to make
 109 this pretty easy, although it may be a little sluggish depending on how many
 110 dependent branches are impacted by the change.  Here is an example:
 111
 112         > git checkout modify-topic-branch  # Checkout the proper branch
 113         > ...update branch...               # Update the branch
 114         > git commit -a                     # Commit your changes
 115         > git checkout top                  # Checkout the top branch
 116         > tg update                         # Recursively merge in new branch
 117
 118 Assuming you change does not introduce any conflicts your done.  All branches
 119 were dependent on your change will have had the changed merged in.  If your
 120 change introduced a conflict you will need to resolve the conflict and then
 121 continue on with the update.
 122
 123 ========================== ADDING A TOPIC BRANCH =========================
 124
 125 Adding a topic branch in TopGit can be pretty straight forward.  If your
 126 adding a non-conflicting patch in parallel with other patches of the same
 127 type, then things are pretty easy and TopGit does all the work.
 128
 129         > git co existing-topic-branch      # Checkout the branch to add after
 130         > tg create new-topic-branch        # Create a new topic branch
 131         > ...update .topmsg...              # Update the branch message
 132         > ...create patch...                # Update with your changes
 133         > git commit -a                     # Commit your changes
 134         > git co dependent-topic-branch     # Checkout dependent branch
 135         > tg depend add new-topic-branch    # Update dependencies
 136         > git checkout top                  # Checkout the top branch
 137         > tg update                         # Recursively merge in new branch
 138
 139 If you need to add your patch in series with another change things are
 140 a little more complicated.  In this case TopGit does not yet support removing
 141 dependencies so you will need to do it by hand, as follows.
 142
 143         > git co existing-topic-branch      # Checkout the branch to add after
 144         > tg create new-topic-branch        # Create a new topic branch
 145         > ...update .topmsg...              # Update the branch message
 146         > ...create patch...                # Update with your changes
 147         > git commit -a                     # Commit your changes
 148         > git co dependent-topic-branch     # Checkout dependent branch
 149         > ...update .topdeps...             # Manually update dependencies
 150         > git commit -a                     # Commit your changes
 151         > tg update                         # TopGit update
 152         > git checkout top                  # Checkout the top branch
 153         > tg update                         # Recursively merge in new branch
 154
 155 Once your done, I find it is a good idea view the repo using the
 156 'tg summary --graphviz' command and verify the updated dependency graph.
 157
 158 ========================= REMOVING A TOPIC BRANCH ========================
 159
 160 Removing a topic branch in TopGit is also currently not very easy.  To remove
 161 a dependent branch the basic process is to commit a patch which reverts all
 162 changes on the branch.  Then that reversion must be merged in to all dependent
 163 branches, the dependencies manually updated and finally the branch removed.
 164 If the branch is not empty you will not be able to remove it.
 165
 166         > git co delete-topic-branch        # Checkout the branch to delete
 167         > tg patch | patch -R -p1           # Revert all branch changes
 168         > git commit -a                     # Commit your changes
 169         > git checkout top                  # Checkout the top branch
 170         > tg update                         # Recursively merge revert
 171         > git co dependent-topic-branch     # Checkout dependent branch
 172         > ...update .topdeps...             # Manually update dependencies
 173         > git commit -a                     # Commit your changes
 174         > tg delete delete-topic-branch     # Delete empty topic branch
 175
 176 Once your done, I find it is a good idea view the repo using the
 177 'tg summary --graphviz' command and verify the updated dependency graph.
 178
 179 ============================ TOPGIT TODO =================================
 180
 181 TopGit is still a young package which seems to be under active development
 182 by its author.  It provides the minimum set of commands needed but there
 183 are clearly areas which simply have not yet been implemented.  My short
 184 list of features includes:
 185
 186   o 'tg summary --deps', option to display a text version of the topic
 187     branch dependency DAC.
 188
 189   o 'tg depend list', list all topic branch dependencies.
 190
 191   o 'tg depend delete', cleanly remove a topic branch dependency.
 192
 193   o 'tg create', cleanly insert a topic branch in the middle
 194     of the graph and properly take care updating all dependencies.
 195
 196   o 'tg delete', cleanly delete a topic branch in the middle
 197     of the graph and properly take care updating all dependencies.