Git Branch Management
Net-SNMP has a number of scripts or shell functions which help manage a git-repo. Specifically, we have a bunch of tools that help test patches, apply patches and perform upward merges based on our Git Workflow. It augments the more day-to-day Git For Developers with detailed project-management issues.
Contents
Getting Started
The bash aliases require that you source the local/gittools/shell-functions in order to get started:
# . ./local/gittools/shell-functions
Once this is done, the rest of the commands on this page will work.
Patch Management
Our Git Workflow states that patches should be applied to the lowest branch possible. IE, if you have a bug fix for nearly every version it should be applied to the lowest current supported version branch. EG, V5-4-patches. But which branch will it apply against cleanly?? How do I do this quickly? We have an answer for you:
Note: all these routines require a clean source tree to start, and will warn you if you have modified files in the tree
nspatchtry
The nspatchtest command can be used to apply a patch to each (currently supported) branch in the tree to see which it will successfully apply to. This is much faster than figuring this out by hand. It takes patch arguments to apply the patch with. The -i switch is required to specify where the patch file is located.
# nspatchtry -p 1 -i /tmp/thepatch
::: Net-SNMP: checking out and applying patch in V5-4-patches
Switched to branch 'V5-4-patches'
Your branch is ahead of 'origin/V5-4-patches' by 5 commits.
::: Net-SNMP: Appling patch
patching file net-snmp/README.snmpv3
::: Net-SNMP: Patch succeeded on V5-4-patches
::: Net-SNMP: cleaning source tree
::: Net-SNMP: checking out and applying patch in V5-5-patches
Switched to branch 'V5-5-patches'
Your branch is ahead of 'origin/V5-5-patches' by 12824 commits.
::: Net-SNMP: Appling patch
patching file net-snmp/README.snmpv3
::: Net-SNMP: Patch succeeded on V5-5-patches
::: Net-SNMP: cleaning source tree
::: Net-SNMP: checking out and applying patch in V5-6-patches
Switched to branch 'V5-6-patches'
Your branch is ahead of 'origin/V5-6-patches' by 25983 commits.
::: Net-SNMP: Appling patch
patching file net-snmp/README.snmpv3
::: Net-SNMP: Patch succeeded on V5-6-patches
::: Net-SNMP: cleaning source tree
::: Net-SNMP: checking out and applying patch in master
Switched to branch 'master'
Your branch is ahead of 'origin/master' by 14786 commits.
::: Net-SNMP: Appling patch
patching file net-snmp/README.snmpv3
::: Net-SNMP: Patch succeeded on master
::: Net-SNMP: cleaning source tree
Patch application results:
Success: V5-4-patches V5-5-patches V5-6-patches master
Fail:
Note the important ending: my patch succeeded against all those branches.
nspatchapply
Now that we know where the patch should be applied, actually applying it is very simple. Simply call the nspatchapply script, which:
- checks out the earliest branch that worked with nspatchtry
- applies the patch
- runs git diff so you can make sure it looks ok
- asks you if it looks ok and if so:
- runs git commit on the results, with any arguments you pass it, to commit the results.
# nspatchapply -m "applying the wonderful patch. Isn't it pretty?" ::: Net-SNMP: Checking out V5-4-patches Switched to branch 'V5-4-patches' Your branch is ahead of 'origin/V5-4-patches' by 5 commits. ::: Net-SNMP: applying the patch -p 1 -i /tmp/thepatch patching file net-snmp/README.snmpv3 diff --git a/net-snmp/README.snmpv3 b/net-snmp/README.snmpv3 index 263c955..8294035 100644 --- a/net-snmp/README.snmpv3 +++ b/net-snmp/README.snmpv3 @@ -1,4 +1,4 @@ -README.snmpv3 +README.snmpv3foo ------------- How to setup SNMPv3, a very brief document for Dave to elaborate and do a better job on since I suck at writing documentation and he commit the results to V5-4-patches? [y/n] y [V5-4-patches 102bde5] applying the wonderful patch. Isn't it pretty? 1 files changed, 1 insertions(+), 1 deletions(-)
Done! Wasn't that easy?
Git Repository Management
Once you have bug-fix patches sprinkled about the various trees, how in the world do you get them all up into the trunk where you want to do your new spiffy feature development in a bug-free environment?
nsrollup
The nsrollup bash function performs the following tasks on a clean tree:
- performs a git pull --all to ensure your branches are up to date
- checks out each branch
- merges the direct previous version into it (eg, it'll roll V5-4-patches into V5-5-patches)
- lets you know about conflicts that you need to resolve
# nsrollup ::: Net-SNMP: Pulling all upstream branches Fetching origin Already up-to-date. ::: Net-SNMP: checking out V5-5-patches Switched to branch 'V5-5-patches' Your branch is ahead of 'origin/V5-5-patches' by 12824 commits. ::: Net-SNMP: merging V5-4-patches into V5-5-patches Merge made by recursive. net-snmp/README.snmpv3 | 2 +- net-snmp/README.tru64 | 4 ++++ 2 files changed, 5 insertions(+), 1 deletions(-) ::: Net-SNMP: checking out V5-6-patches Switched to branch 'V5-6-patches' Your branch is ahead of 'origin/V5-6-patches' by 25983 commits. ::: Net-SNMP: merging V5-5-patches into V5-6-patches Auto-merging net-snmp/README.snmpv3 Auto-merging net-snmp/README.tru64 Merge made by recursive. dist/release | 2 +- net-snmp/README.snmpv3 | 2 +- net-snmp/README.tru64 | 2 ++ 3 files changed, 4 insertions(+), 2 deletions(-) ::: Net-SNMP: checking out master Switched to branch 'master' Your branch is ahead of 'origin/master' by 14786 commits. ::: Net-SNMP: merging V5-6-patches into master Merge made by recursive. dist/release | 2 +- net-snmp/README.snmpv3 | 2 +- net-snmp/README.tru64 | 2 ++ 3 files changed, 4 insertions(+), 2 deletions(-)
-------------------------------
Updated the following branches:
V5-5-patches V5-6-patches master
Stopping Merging During Release-Candidates
Our development policy says that during the release candidate series, all patches must be voted on in the -coders list. Thus, it's not appropriate for these to be automatically rolled upward, as that's the job of the release engineer for that release to do. Thus, if a dist/release file exists and it contains a branch name followed by a magical 'rc' keyword, this branch will be excluded from the merging. EG:
V5-6-patches rc
Will cause it to be ignored for merging. Changes in V5-6-patches will still be rolled into V5-7-patches, though (which will often include changes to the dist/release file itself; but that's ok. It can list multiple releases if need be).
Checking the pretty results tree
The gitk tool is highly useful (with the --all switch) for showing the resulting prettiness that you just created. For example, in the above examples it produced a bunch of merges that are shown graphically as follows:
