gitworkflows(7) is a set of workflow used by git.git.
These slides will show you how it works with simple commit graphs.
other slides: https://docs.google.com/spreadsheets/d/1VZMz_31Z7FQBnK139o8yMqzwrTJgZWtPqgoG-mx1zh0/edit?usp=sharing
2. What’s gitworkflows?
A set of workflows used in the Git project itself.
Details are described in the online manual
gitworkflows(7) shipped with Git.
3. Why gitworkflows?
● You can push -f for integration branches
● You can merge topic branches casually
● You can keep master stable with clear
history
● Scalable to a large number of developers
You know you can freely modify your commits
and topic branches with Git. You can do it for
integration branches with gitworkflows.
4. In these slides
I’ll show you how gitworkflows* work with
simple commit graphs.
It helps you to understand gitworkflows even
though they are little complicated.
Here we go.
* Maybe slightly different from actual workflows used by git.git, because these slides are based on my
interpretation of the gitworkflows(7).
5. There is an initial commit.
Let’s start from here.
11. No. ‘master’ can’t be reset after topics once merged
(and pushed to public repositories).
Use a ‘throw-away’ integration branch instead.
12. ‘pu’ is the name of the throw-away integration branch.
Stands for ‘Proposed Update’
pu
13. ‘pu’ should be branched from the tip of the most advanced
non-throw-away branch.
‘master’ would be fine at this time.
(You may use git branch pu master)
14. Merge topic A…
(checkout pu and merge topic-A. You can use --
no-ff merge like below if you want)
merge
17. Then, let’s do tests especially about interactions among the
merged topics/features. (They can’t be tested on each
branch)
18. BTW you can push ‘pu’ to public repositories if needed.
(push origin pu)
e.g. a CI server is watching a public repository for running
automated tests and you want to push for it.
19. You may find some bugs/lacks of functionalities on ‘pu’
with integrated state of the three topics.
20. One of them was introduced on topic A
So fix it on that topic.
commit
28. Now you’ve got new ‘pu’ that cleanly merged three
topics.
29. Note that all developers involved including you can’t work
on ‘pu’. All topics have to be forked off from ‘master’
30. Without reset, resulting branch / commit graph would be little
more complicated, even though they have identical trees.
trees of these two commits
are identical
- with reset
- without reset
31. OK. Let’s push new ‘pu’ to public repositories and test it.
32. You have to do push -f origin pu or push origin
+pu if you’ve pushed old ‘pu’ before, because new ‘pu’ isn’t
direct descendant of the old ‘pu’ on origin.
33. After test, you found that two features from topic A, B were
good and stable but one from topic C wasn’t.
34. You decide to merge topic A and B into ‘master’ because
they are stable enough.
42. Merge topic C, then push ‘master’ and ‘pu’.
Again, you have to use forced push for ‘pu’, so you may say:
git push origin master +pu
(prefix ‘+’ for the branch name means forced push.)
merge
43. You want more time to stabilize topic C.
So you decide to make the first release with two features
already merged into ‘master’.
51. You find two of three active topic branches look good
after tests. But you are unsure for...
Good
Good
52. Unsure for: - Stability of the implementation
- Excellence of the design
- Requirement of the feature
etc.
53. It means that keeping them in ‘pu’ is tiring because they
won’t be changed for a while, but merging them into
‘master’ can’t be done because they may be changed or
possibly deleted.
54. In other words, you need an integration branch for
stabilizing, testing or previews for those topics.
55. ‘next’ is the integration branch for such use. It’s like a
hybrid of throw-away and non throw-away. You can
reset ‘next’ with an announcement for developers, but
don’t do it so frequently.
next
tag
56. ‘next’ will be branched from ‘master’.
(branch next master)
57. Merge the remaining old active topic, C…
(checkout next and merge topic-C)
merge
65. Note that you and developers involved cannot work on
‘next’ because it sometimes get reset. So all feature
branches should be forked off from ‘master’
66. What are the differences between ‘next’ and ‘pu’?
75. Note that you can merge the new branch head of topic D
into ‘pu’ first if needed.
(e.g. it has too large impact to merge into ‘next’)
merge into ‘pu’ first
(+ push and test)
if it looks good,
then merge into ‘next’
reconstruct ‘pu’.
this is identical graph
shown in previous page
77. You found a topic kept in ‘pu’, topic E, was totally broken
and the topic developer can’t fix it right away. When it
happened, just reconstruct ‘pu’ ignoring broken
branches.
Broken
88. Again, note that ‘next’ shouldn’t be reset easily like ‘pu’.
When you want to redo something on ‘next’, just revert or re-
merge instead.
89. But ‘next’ can be reset with announcements for involved
developers when it get awfully dirty with a number of revert
and duplicate merges.
90. And you’ll also have chances to reset ‘next’ after feature
release. It will be shown later.
Let’s keep developing for the second release for now.
91. When you think topics merged into ‘next’ are stable / having
good design / etc. you can merge them into ‘master’
Good enough to be
merged into ‘master’
92. When you think topics merged into ‘next’ are stable / having
good design / etc. you can merge them into ‘master’
Good enough to be
merged into ‘master’
93. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘master’
new topic
94. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘master’
merge
95. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘master’
good enough
for master
96. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘master’
merge
97. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘master’
good enough
for next
98. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘master’
merge
reset and
merge
99. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘master’
new topic
100. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘master’
merge
101. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘master’
good enough
for next
102. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘master’
merge
reset and
merge
103. These merges in ‘pu’ -> ‘next’ -> ‘master’ order,
downstream-ward propagation of features, are called
‘graduate’.
105. Once a topic merged into ‘master’, it will be regarded as
‘master’ itself. So fix branches should be created on
‘master’ for bugs of ‘master’.
fix-branch for the bug
106. Merge it into (‘pu’ and) ‘next’ first.
merge
reset and merge
107. Then merge it into ‘master’ if it looks good.
merge
108. Note that you can merge the fix branch into ‘master’ directly
when the commits in fix branch are trivial.
fix-branch for the bug
109. Note that you can merge the fix branch into ‘master’ directly
when the commits in fix branch are trivial.
merge
110. But after that, don’t forget to merge ‘master’ into ‘next’ for
the fix will be included in ‘next’
(‘next’ must have the bug because it has all topics merged
into ‘master’)
merge
reset and merge
111. There is another situation for fixing bugs.
If the release v1.0.0 have a bug, how should we address it?
a bug found
112. Fix it on ‘master’ and let v1.0.0 users upgrade to ‘master’?
But some v1.0.0 users don’t want to use new features
merged into ‘master’.
113. So you want a new integration branch only for bug fixing.
‘maint’ is such a branch. It will be branched from the latest
feature release, i.e. v1.0.0.
maint
create branch
114. The fix branch have to be branched from ‘maint’.
Don’t branch from ‘master’ or any upstream.
fix-branch for the bug
115. If you branch the fix branch for ‘maint’ from ‘master’...
*WRONG*
fix-branch for the bug
*WRONG*
116. When the fix branch merged into ‘maint’, additional topics
are also merged into ‘maint’. Those downwards merging will
break ‘maint’ branch.
*WRONG*
merge
*WRONG*
unintentionally
merged commits
117. You can handle this case by cherry-pick the commit into
‘maint’, but you should take care where you fork off from.
cherry-pick
workaround
118. So the fix branch should be forked off from ‘maint’.
As a general rule, fork off topics from the oldest integration
branch which the topics will be finally merged into.
fix-branch for the bug
119. Basically merge the fix branch for ‘maint’ into ‘next’ (or ‘pu’)
first as usual because ‘maint’ never get reset.
merge
reset and merge
120. Then merge it into ‘maint’ when it looks good on ‘next’.
merge
122. Of course you can merge fix branches directly into ‘maint’
when they are trivial.
merge
123. Sometimes you should merge ‘maint’ into ‘master’, and
merge ‘master’ into ‘next’ for propagation of the fixes.
Periodic upward merges are good habits.
124. Sometimes you should merge ‘maint’ into ‘master’, and
merge ‘master’ into ‘next’ for propagation of the fixes.
Periodic upward merges are good habits.
merge
125. Sometimes you should merge ‘maint’ into ‘master’, and
merge ‘master’ into ‘next’ for propagation of the fixes.
Periodic upward merges are good habits.
126. Sometimes you should merge ‘maint’ into ‘master’, and
merge ‘master’ into ‘next’ for propagation of the fixes.
Periodic upward merges are good habits.
merge
127. Sometimes you should merge ‘maint’ into ‘master’, and
merge ‘master’ into ‘next’ for propagation of the fixes.
Periodic upward merges are good habits.
merge
128. Sometimes you should merge ‘maint’ into ‘master’, and
merge ‘master’ into ‘next’ for propagation of the fixes.
Periodic upward merges are good habits.
merge
129. Sometimes you should merge ‘maint’ into ‘master’, and
merge ‘master’ into ‘next’ for propagation of the fixes.
Periodic upward merges are good habits.
reset and merge
130. Sometimes you should merge ‘maint’ into ‘master’, and
merge ‘master’ into ‘next’ for propagation of the fixes.
Periodic upward merges are good habits.
131. When some fixes accumulated in ‘maint’, publish a fix-
release.
132. Tag v1.0.1 on ‘maint’ for the fix-release and push it.
v1.
0.1
tag
133. Well, after a while you want to make a new feature-release.
And you want have a code-freeze period for this release.
134. To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
merge fix branches only
while frozen
135. To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
fix
feature
136. To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
feature
fix
137. To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
feature
merging maint is ok
fix
138. To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
feature
merging fix branches
are also ok
fix
139. To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
feature
Don’t merge feature
branches
fix
140. To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
feature
Don’t merge feature
branches
fix
141. To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
feature
fix
142. To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
feature
fix
even though good
enough for master...
143. To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
feature
Don’t merge ANY
feature branches
fix
144. To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
feature
Don’t merge ANY
feature branches
fix
145. To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
feature
fix
146. You can merge feature topics into ‘next’ for integration of
them while ‘master’ is frozen. So you don’t have to stop
developing for the code-freeze.
merging feature
branches are OKay
fix
feature
fix
147. You can merge feature topics into ‘next’ for integration of
them while ‘master’ is frozen. So you don’t have to stop
developing for the code-freeze.
merging fix branches
are also OKay
fix
feature
fix
148. You can merge feature topics into ‘next’ for integration of
them while ‘master’ is frozen. So you don’t have to stop
developing for the code-freeze.
149. You can merge feature topics into ‘next’ for integration of
them while ‘master’ is frozen. So you don’t have to stop
developing for the code-freeze.
rebase
rebasing active topics
are OKay
150. You can merge feature topics into ‘next’ for integration of
them while ‘master’ is frozen. So you don’t have to stop
developing for the code-freeze.
rebase
rebasing active topics
are OKay
151. You can merge feature topics into ‘next’ for integration of
them while ‘master’ is frozen. So you don’t have to stop
developing for the code-freeze.
reverting or dropping
active branches are also
OKay
revert
152. You can merge feature topics into ‘next’ for integration of
them while ‘master’ is frozen. So you don’t have to stop
developing for the code-freeze.
reverting or dropping
active branches are also
OKay
154. Before tagging, make sure ‘maint’ is fully merged into
‘master’ by git merge maint on ‘master’. If not merged,
some fixes will be missing from the new release.
Already fully merged
into master in this case
155. Now release it. Tag v1.1.0 on ‘master’ for the feature-
release and push it.
tag
v1.
1.0
156. New release has done. But you have some tasks for the
‘next’ and ‘maint’ after feature-release
157. Let’s do for ‘next’.
At first reset ‘next’ to ‘master’
reset to
master
leave a tag for in
case messed up
158. Then merge active topics they weren’t included in the last
release. (And rebuild ‘pu’ if needed)
merge active
branches
159. Then merge active topics they weren’t included in the last
release. (And rebuild ‘pu’ if needed)
merge active
branches
160. Then merge active topics they weren’t included in the last
release. (And rebuild ‘pu’ if needed)
check diff for
making sure that
they are
equivalentdiff
161. Then merge active topics they weren’t included in the last
release. (And rebuild ‘pu’ if needed)
rebuild pu
162. This rewind and reconstruction of ‘next’ is for cleaning up the
history of it. Actually you can do this anytime with an
announcement. But it is good point to do this right after a
feature release.
163. This rewind and reconstruction of ‘next’ is for cleaning up the
history of it. Actually you can do this anytime with an
announcement. But it is good point to do this right after a
feature release.
164. Next, let’s see about ‘maint’
The task for ‘maint’ is simple. Just fast-forward ‘maint’ to
‘master’.
Fast-Foward
to master
165. This is done by git merge --ff-only master on
‘maint’. If it fail, the last release is missing some fixes
because ‘maint’ must have some commits that are not in
‘master’.
Fast-Foward
to master
166. If you merge ‘maint’ into ‘master’ before the release like
already shown, the fast-forward will succeed.
167. Note that if you want keep maintenance branch for the
previous feature-release, you can leave another maint
branch, e.g. maint-1.0, for it.
maint-1.0
168. After the feature-release, repeat the same workflows
already shown. This is the gitworkflows(7). Keep on
developing with it.
New topic and...
169. Conclusion (1/2)
● Use throw-away integration branch like pu
● Merge topics into the throw-away(TA) first
● Test in TAs before merging topics into master
● You can use hybrid of TA and non-TA like
next
● next can be reset with announcements.
● master and maint cannot be reset
170. Conclusion (2/2)
● Don’t base your work on pu or next
● Fork off topics from the oldest integ-branch
which the topics will be finally merged into
● Merge integration branches upwards
● Tag master for feature-releases
● Tag maint for fix-releases
171. See also
● gitworkflows(7)
● Documentation/SubmittingPatches
in Git source tree
● MaintNote in ‘todo’ branch of git.git
● the Git Blame blog by Junio C Hamano
173. Q: What is the difference between next and pu?
A: It depends.
gitworkflows(7) saids pu, throw-away, is for testing the
interaction of topics but according to the recent MaintNotes in
the git.git, pu is a sort of reminder for the maintainer. next is
said to be for testing/polishing for master in both documents.
IMHO pu is a working space and next is a staging area for
master. It looks like working tree and index of Git itself.
174. Q: Do I have to keep {‘pu’, ‘next’, ‘maint’}
A: No, you don’t.
Just create and keep them if you need. But I recommend you
to use a throw-away at least. You may keep it in your local
repos only (i.e. make sure tests are succeeded and then
push master).
I’ve seen a project that have only ‘master’, ‘pu’ and another
project that have ‘master’, ‘master-pu’, ‘maint’, ‘maint-pu’.
175. Q: Do I have to keep so many topics?
A: Yes.
You have to keep them until they’ve been merged into
‘master’ or ‘maint’
But you can assign someone you trust to maintain a certain
subsystem with gitworkflows. Then you can just merge
his/her ‘master’ into your ‘master’. (actually you need a
throw-away)
This is the reason why gitworkflows is thought to be scalable.
176. Q: Do I have to merge a single branch repeatedly?
A: Yes.
When you become tired of resolving identical conflicts,
enable git-rerere(1). The ‘rerere’ stands for Reuse Recorded
Resolution. It will help you to resolve conflicts that have been
resolved once before.
177. Q: May I use GitHub pull requests with gitworkflows?
A: Yes, of course.
For the git.git, GitHub pull requests are simply ignored but it’s
just a policy of the project.
“Merge Workflow” in the online manual gitworkflows(7) will
suit for GitHub users.