From 9fc325737bd0fc5f5539763570cdde792859326a Mon Sep 17 00:00:00 2001 From: Brian Behlendorf Date: Thu, 20 Nov 2008 16:54:29 -0800 Subject: [PATCH] Update GIT documentation to describe the new DAC setup --- GIT | 56 +++++++++++++++++++++++++++++++------------------------- 1 file changed, 31 insertions(+), 25 deletions(-) diff --git a/GIT b/GIT index 578e731..0525c8c 100644 --- a/GIT +++ b/GIT @@ -8,16 +8,16 @@ Three major concerns were on our mind when setting up this project. improvements and not get locked in to an old version of the code base. o Secondly, we wanted to be able to easily manage our changes in terms - of a patch stack. This allows us to easily isolate specific changes - and push them upstream for inclusion. It also allows us to easily - update or drop specific changes based on what occurs upstream. + of a patch stack or graph. This allows us to easily isolate specific + changes and push them upstream for inclusion. It also allows us to + easily update or drop specific changes based on what occurs upstream. o Thirdly we needed our DVCS to be integrated with the management of this - patch stack. We have tried other methods in the past such as SVN+Quilt - but have found managing the patch stack becomes cumbersome. By using - Git+TopGit to more tightly integrate our patch stack in to the repo + patch stack or graph. We have tried other methods in the past such as + SVN+Quilt but have found managing the patch stack becomes cumbersome. + By using Git+TopGit to more tightly integrate our patches in to the repo we expect several benefits. One of the most important will be the - ability to easily work on the patch stack with a distributed developer + ability to easily work on the patch's with a distributed development team, additionally the repo can track patch history, and we can utilize Git to merge patches and resolve conflicts. @@ -59,28 +59,34 @@ a summary command which shows all the branches and a brief summary for each branch obtained from the .topmsg files. > tg summary - 0 t/LAST [PATCH] LAST - t/feature-commit-cb [PATCH] zfs commit callbacks - t/fix-clock-wrap [PATCH] fix clock wrap - t/fix-dnode-cons [PATCH] fix dnode constructor + 0 feature-branch [PATCH] feature-branch + feature-commit-cb [PATCH] feature commit cb + feature-zap-cursor-to-key [PATCH] feature zap cursor to key ... -By convention all TopGit branches are prefixed with 't/', and the Linux -ZFS repo also introduces the convention that the top most development -branch be called 't/LAST". This provides a consistent label to be used -when you need to reference the branch which contains the union of all -topic branches. +By convention all TopGit branches are usually prefixed with 't/', however +I have chosen not to do this for simplicity. A different convention I have +adopted is to tag the top most TopGit branch as 'top' for easy reference. +This provides a consistent label to be used when you need to reference the +branch which contains the union of all topic branches. One thing you may also notice about the 'tg summary' command is it does -not show the branches in dependent order. While this project only expresses -a single dependency per branch TopGit implements dependencies as a DAC just -like Git. To see the dependencies you will need to use the --graphviz -option and pipe the result to dot for display. The following command while -long works fairly well for me. Longer term it would be nice to update this -option to use a preferred config options stored in the repo if they exist. - - > tg summary --graphviz | dot -Txlib -Nfontsize=8 -Eminlen=0.01 \ - -Grankdir=LR -Nheight=0.3 -Nwidth=2 -Nfixedsize=true +not show the branches in dependent order. This is done because TopGit allows +each branch to express multiple dependencies as a DAC. Initially this seemed +like an added complication which I planned to avoid by just implementing a +stack using the graph. However, this ended up being problematic because +with a stack when a change was made to a branch near the base, it was a +very expensive operation to merge the change up to the top of the stack. +By defining the dependencies as a graph it is possible to keep the depth +much shallower thus minimizing the merging. It has also proved insightful +as to each patches actual dependencies. + +To see the dependencies you will need to use the --graphviz option and pipe +the result to dot for display. The following command works fairly well for +me. Longer term it would be nice to update this option to use a preferred +config options stored in the repo. + + > tg summary --graphviz | dot -Txlib -Nfontsize=8 ========================= UPDATING A TOPIC BRANCH ======================== -- 1.8.3.1