Documenting Proper Git Usage | Linux Journal
Jonathan Corbet wrote a doc for inclusion within the kernel tree, describing
finest practices for merging and rebasing git-based kernel repositories. As he put
it, it represented workflows that had been really in present use, and it was a dwelling
doc that hopefully can be added to and corrected over time.
The inspiration for the doc got here from noticing how often Linus
was sad with how different individuals—sometimes subsystem maintainers—dealt with
their git timber.
It’s attention-grabbing to notice that earlier than Linus wrote the git instrument, branching and
merging was nearly unprecedented within the Open Source world. In CVS, it was a
nightmare horror of leechcraft and damaged magic. Other instruments weren’t a lot better.
One of the first motivations behind git—apart from blazing pace—was, in
reality, to make branching and merging trivial operations—and they also have turn into.
One of the offshoots of branching and merging, Jonathan wrote, was rebasing—altering the patch historical past of a neighborhood repository. The advantages of rebasing are
incredible. They could make a repository historical past cleaner and clearer, which in flip
could make it simpler to trace down the patches that launched a given bug. So
rebasing has a direct worth to the event course of.
On the opposite hand, used poorly, rebasing could make a giant mess. For instance, suppose
you rebase a repository that has already been merged with one other, after which merge
them once more—insane soul demise.
So Jonathan defined some good guidelines of thumb. Never rebase a repository that is
already been shared. Never rebase patches that come from another person’s repository.
And typically, merely by no means rebase—until there is a real purpose.
Since rebasing modifications the historical past of patches, it depends on a brand new “base” model,
from which the later patches diverge. Jonathan advisable selecting a base model
that was typically considered extra secure somewhat than much less—a brand new model or a
launch candidate, for instance, somewhat than simply an arbitrary patch throughout common
Jonathan additionally advisable, for any rebase, treating all of the rebased patches as new
code, and testing them completely, even when they’d been examined already previous to
“If”, he stated, “rebasing is proscribed to personal timber, commits are based mostly on a
well-known start line, and they’re nicely examined, the potential for bother is
Moving on to merging, Jonathan identified that just about 9% of all kernel commits
had been merges. There had been greater than 1,000 merge requests within the 5.1 growth cycle
He identified within the doc that, though “many initiatives require that branches in
pull requests be based mostly on the present trunk in order that no merge commits seem within the
historical past”, the kernel had no such requirement. Merges had been thought-about completely
orderly methods of doing enterprise, and builders mustn’t attempt to rebase their
branches to keep away from merges.
An attention-grabbing factor about kernel growth is that the hierarchy of
maintainership tends to favor a hierarchy of git repository maintainers. It’s not
unusual for one or a couple of individuals to handle a branched kernel repository, and to
have builders managing branches of that tree, with different builders in flip
managing branches of these.
For mid-level maintainers, Jonathan identified, there are two related conditions:
merging a tree from decrease within the hierarchy into your individual and merging your individual
tree increased up towards Linus’ top-level tree.
Jonathan advisable that for mid-level maintainers accepting merges from decrease timber,
maintainers not search to cover the merge request and, in actual fact, ought to add a
commit message or changelog entry, explaining the patches that went into the merge.
Jonathan additionally identified that the “Signed-Off-By” tags had been essential parts of
commit messages that helped monitor duty in addition to essential debugging
data. He steered that every one maintainers ought to proceed to make use of them and to
confirm them when merging from different timber. Jonathan stated, “Failure to take action
threatens the safety of the event course of as an entire.”
That recommendation referred to downstream timber, however Jonathan had some very attention-grabbing
factors to make about merging from upstream timber. This is whenever you’re engaged on
your tree, and also you need to be sure you’re updated with the latest-and-greatest
tree from Linus or somebody near him. Of course, doing so would make your individual
life barely simpler, since you’d be updated, you could possibly take a look at your code in opposition to
the tip of the tree, and so forth. Still, Jonathan recommended in opposition to it.
For one factor, you could possibly be bringing different individuals’s bugs into your individual tree,
destabilizing your take a look at code, and you then’d have the uncertainty of figuring out that
your code was really strong and able to submit additional upstream.
Another temptation is to do a merge from the upstream supply proper earlier than
submitting your individual merge request to make sure that your request will not encounter any
conflicts. However, as Jonathan stated, “Linus is adamant that he would a lot somewhat
see merge conflicts than pointless again merges. Seeing the conflicts lets him
know the place potential drawback areas are. He does a whole lot of merges (382 within the 5.1
growth cycle) and has gotten fairly good at battle decision—usually higher
than the builders concerned.”
Instead, when you do discover a battle that may present up when Linus does the merge,
you must say one thing about it within the pull request, so Linus sees that you simply see
As a final resort, for significantly nutty instances, Jonathan stated, you could possibly create
one other department, with your individual battle resolutions, and level Linus to that so he
can see the way you’d resolve the issues your self. The pull request, nonetheless, ought to
be for the unresolved department.
Doing a take a look at merge in that manner is ok, he stated. It helps if there’ll
be any conflicts, so you possibly can talk higher to the upstream maintainers.
He provided some extra good recommendation and closed by saying:
The tips laid out
above are simply that: tips. There will all the time be conditions that decision out for
a special answer, and these tips mustn’t stop builders from doing
the correct factor when the necessity arises. But one ought to all the time take into consideration whether or not
the necessity has actually arisen and be ready to clarify why one thing irregular wants
to be carried out.
And…Linus replied that he appreciated the entire doc.
David Rientjes from Google reported that he really had been within the strategy of
writing an inside doc to be used by Google engineers, discussing this very matter. He
was thrilled that Jonathan had carried out a greater job explaining it than his personal effort.
Geert Uytterhoeven additionally appreciated the brand new doc, and he provided some spelling and grammar
Only Theodore Ts’o had any vital criticism to supply. He felt a transparent
distinction ought to be made between reordering patches (which he felt was what most
individuals considered after they talked about rebasing), versus really altering or
eradicating commits which have already gone into the tree. Both had been technically
rebasing, but each had been actually fairly completely different operations.
Jonathan replied to this, suggesting that possibly the doc might refer individually to
“rebasing” and “history modification”. And, Ted agreed this may be higher.
End of thread. I like seeing this type of documentation go into the kernel. It’s
not the identical as general-purpose git recommendation, as a result of it is particular to kernel
growth processes and insurance policies which are already in place. At the identical time,
it is doubtlessly very helpful to different large-scale initiatives that may need to mimic
the Linux kernel growth course of. All open-source initiatives primarily mimic
the kernel growth course of anyway—Linus is the one who first found and
popularized the strategies of how one can run an open-source mission—and there tends to
be a whole lot of knowledge in his growth coverage choices even now.
Note: when you’re talked about above and need to publish a response above the remark part, ship a message along with your response textual content to firstname.lastname@example.org.