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.  This allows us to easily isolate specific changes
  12     and push them upstream for inclusion.  It also allows us to easily
  13     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.  We have tried other methods in the past such as SVN+Quilt
  17     but have found managing the patch stack becomes cumbersome.  By using
  18     Git+TopGit to more tightly integrate our patch stack 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 stack with a distributed developer
  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 http://repo.or.cz/w/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 http://eris.llnl.gov/git/zfs.git zfs
  53         > cd zfs
  54         > tg remote --populate origin
  55
  56 Now that you have the Linux ZFS repo the first thing you will probably
  57 want to do is have a look at all the topic branches.  TopGit provides
  58 a summary command which shows all the branches and a brief summary for
  59 each branch obtained from the .topmsg files.
  60
  61         > tg summary
  62  0      t/LAST                          [PATCH] LAST
  63         t/feature-commit-cb             [PATCH] zfs commit callbacks
  64         t/fix-clock-wrap                [PATCH] fix clock wrap
  65         t/fix-dnode-cons                [PATCH] fix dnode constructor
  66         ...
  67
  68 By convention all TopGit branches are prefixed with 't/', and the Linux
  69 ZFS repo also introduces the convention that the top most development
  70 branch be called 't/LAST".  This provides a consistent label to be used
  71 when you need to reference the branch which contains the union of all
  72 topic branches.
  73
  74 One thing you may also notice about the 'tg summary' command is it does
  75 not show the branches in dependent order.  While this project only expresses
  76 a single dependency per branch TopGit implements dependencies as a DAC just
  77 like Git.  To see the dependencies you will need to use the --graphviz
  78 option and pipe the result to dot for display.  The following command while
  79 long works fairly well for me.  Longer term it would be nice to update this
  80 option to use a preferred config options stored in the repo if they exist.
  81
  82         > tg summary --graphviz | dot -Txlib -Nfontsize=8 -Eminlen=0.01 \
  83         -Grankdir=LR -Nheight=0.3 -Nwidth=2 -Nfixedsize=true
  84
  85 ========================= UPDATING A TOPIC BRANCH ========================
  86
  87 Updating a topic branch in TopGit is a pretty straight forward but there
  88 are a few rules you need to be aware of.  The basic process involves
  89 checking out the relevant topic branch where the changes need to be made,
  90 making the changes, committing the changes to the branch and then merging
  91 those changes in to dependent branches.  TopGit provides some tools to make
  92 this pretty easy, although it may be a little sluggish.  Here is an example:
  93
  94         > git checkout t/feature-commit-cb  # Checkout the proper branch
  95         > ...update branch...               # Update the branch
  96         > git commit -a                     # Commit your changes
  97         > git checkout t/LAST               # Checkout the LAST branch
  98         > tg update                         # Recursively merge in new branch
  99
 100 Assuming you change does not introduce any conflicts your done.  All branches
 101 were dependent on your change will have had the changed merged in.  If your
 102 change introduced a conflict you will need to resolve the conflict and then
 103 continue on with the update.
 104
 105 ========================== ADDING A TOPIC BRANCH =========================
 106
 107 Adding a topic branch in TopGit is a little more complicated.  When adding
 108 a new branch to the end of the patch graph things are pretty easy and TopGit
 109 does all the work.  However, I expect out common case to be adding patches
 110 to the middle of the graph.  TopGit will allow you to do this but you must
 111 be careful to manually update the dependency information in the .topdeps
 112 file.
 113
 114         > git co t/existing-topic-branch    # Checkout the branch to add after
 115         > tg create t/new-topic-branch      # Create a new topic branch
 116         > ...update .topmsg...              # Update the branch message
 117         > ...create patch...                # Update with your changes
 118         > git commit -a                     # Commit your changes
 119         > git co t/dependent-topic-branch   # Checkout dependent branch
 120         > ...update .topdeps...             # Manually update dependencies
 121         > git commit -a                     # Commit your changes
 122         > tg update                         # TopGit update
 123         > git checkout t/LAST               # Checkout the LAST branch
 124         > tg update                         # Recursively merge in new branch
 125
 126 ========================= REMOVING A TOPIC BRANCH ========================
 127
 128 Removing a topic branch in TopGit is also currently not very easy.  To remove
 129 a dependent branch the basic process is to commit a patch which reverts all
 130 changes on the branch.  Then that reversion must be merged in to all dependent
 131 branches, the dependencies manually updated and finally the branch removed.
 132 If the branch is not empty you will not be able to remove it.
 133
 134         > git co t/del-topic-branch         # Checkout the branch to delete
 135         > tg patch | patch -R -p1           # Revert all branch changes
 136         > git commit -a                     # Commit your changes
 137         > git checkout t/LAST               # Checkout the LAST branch
 138         > tg update                         # Recursively merge revert
 139         > git co t/dependent-topic-branch   # Checkout dependent branch
 140         > ...update .topdeps...             # Manually update dependencies
 141         > git commit -a                     # Commit your changes
 142         > tg delete t/del-topic-branch      # Delete empty topic branch
 143
 144 ============================ TOPGIT TODO =================================
 145
 146 TopGit is still a young package which seems to be under active development
 147 by its author.  It provides the minimum set of commands needed but there
 148 are clearly areas which simply have not yet been implemented.  My short
 149 list of features includes:
 150
 151   o 'tg summary --deps', option to display a text version of the topic
 152     branch dependency DAC.
 153
 154   o 'tg depend list', list all topic branch dependencies.
 155
 156   o 'tg depend delete', cleanly remove a topic branch dependency.
 157
 158   o 'tg create', cleanly insert a topic branch in the middle
 159     of the graph and properly take care updating all dependencies.
 160
 161   o 'tg delete', cleanly delete a topic branch in the middle
 162     of the graph and properly take care updating all dependencies.