Skip to content

Commit 2781bad

Browse files
chriscoolchriscool
committed
rn-19: add article about git-series
1 parent 860469e commit 2781bad

File tree

1 file changed

+219
-2
lines changed

1 file changed

+219
-2
lines changed

‎rev_news/drafts/edition-19.md‎

Lines changed: 219 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,226 @@ This edition covers what happened during the month of August 2016.
1717

1818
## Discussions
1919

20-
<!---
2120
### General
22-
-->
21+
22+
*[git-series presentation at the LinuxCon North America](https://www.youtube.com/watch?v=68XsuXlWiWU&index=23&list=PLGeM09tlguZQyemL0Y5CdpEFrBs-hGGM8)
23+
24+
There were a significant number of Git related presentations at the
25+
[LinuxCon North America 2016 in Toronto](http://events.linuxfoundation.org/events/linuxcon-north-america)
26+
from August 22 to August 24, and they happened to be recorded:
27+
28+
-[Who Authored the Kernel? Recovering Token-Level Authorship Information from Git by Daniel German](https://www.youtube.com/watch?v=iXZV5uAYMJI&index=4&list=PLGeM09tlguZQyemL0Y5CdpEFrBs-hGGM8), see also the [LWN article](http://lwn.net/Articles/698425/).
29+
-[Versions All the Way Down: Versioning Commits and Patches with Git-Series by Josh Triplett, Intel](https://www.youtube.com/watch?v=68XsuXlWiWU&index=23&list=PLGeM09tlguZQyemL0Y5CdpEFrBs-hGGM8).
30+
-[Tracking Huge Files with Git LFS by Tim Pettersen, Atlassian](https://www.youtube.com/watch?v=yuKAV5cCcTw&list=PLGeM09tlguZQyemL0Y5CdpEFrBs-hGGM8&index=24).
31+
-[Terrible Ideas in Git by Corey Quinn, FutureAdvisor](https://www.youtube.com/watch?v=Wr7ulql0Exo&index=25&list=PLGeM09tlguZQyemL0Y5CdpEFrBs-hGGM8).
32+
-[Git and Testing by your own Christian Couder](https://www.youtube.com/watch?v=TcgyVWBg8EQ&list=PLGeM09tlguZQyemL0Y5CdpEFrBs-hGGM8&index=26)
33+
34+
One of the most attended was Josh's presentation
35+
([slides](http://events.linuxfoundation.org/sites/events/files/slides/git-series.pdf),
36+
[video](https://www.youtube.com/watch?v=68XsuXlWiWU&index=23&list=PLGeM09tlguZQyemL0Y5CdpEFrBs-hGGM8))
37+
about git-series. Josh had already
38+
[announced git-series on the mailing list](https://public-inbox.org/git/20160729064055.GB25331@x/)
39+
which had generated some amount of dicussion about how the different
40+
efforts to store more data and metadata related to patch series using
41+
git itself could collaborate.
42+
43+
In his talk Josh started by explaining the problems with the current
44+
way of handling a patch series.
45+
46+
One problem is that when you get feedback, you have to rework your
47+
patch series, so you create another version of your patch series. But
48+
then what happens to the previous version of the series?
49+
50+
You have to keep it, because people can tell you that they liked
51+
better what your previous version did, and because some people are
52+
actually interested in the real history of your code.
53+
54+
You could use the reflog to keep it, but it is effemeral by default
55+
and it is not easy to push or pull. You could also dig an email from
56+
your sent-mail folder or a mailing list archive.
57+
58+
So a fundamental problem is that Git tracks only curated history
59+
but we need more than that, we need the history of history.
60+
61+
`git submodule` could be used to track that but people generally have
62+
a bad experience with `git submodule`. It's also possible to manage
63+
patches outside Git. There are tools like for example quilt that can
64+
be used for this purpose, but then you loose the power of working with
65+
Git.
66+
67+
Another possibility is to use branches with version names like
68+
feature-v1, feature-v2 and so on. But soon you could have names like
69+
feature-v8-rebased-on-3-4-alice-fix and then "everybody who worked in
70+
a corporate environment would feel right at home".
71+
72+
Such solutions anyway don't solve the problem of managing the cover
73+
letter and the base commit which is the commit you started your patch
74+
series from.
75+
76+
They also don't solve the problem of collaboration. One rule of
77+
collaboration is to never rewrite published history, but then how do
78+
you collaborate on history that needs rewritting?
79+
80+
Emailing patches back and forth is not a good solution for some kinds
81+
of work like backporting a feature, preparing a distribution package,
82+
rebasing stacks of patches sitting on top of upstream code.
83+
84+
'git-series' has been developed to fix all those problems. It tracks
85+
the history of a patch series, and also tracks its cover letter and its
86+
base.
87+
88+
Then josh gave a demo.
89+
90+
To create a series called "feature" based on v4.7, you would run for
91+
example:
92+
93+
```
94+
git series start feature
95+
-> HEAD is now detached at fa8410b Linux 4.8-rc3
96+
git checkout v4.7
97+
-> HEAD is now at 523d939... Linux 4.7
98+
git series base v4.7
99+
-> Set patch series base to 523d939 Linux 4.7
100+
vim README
101+
git commit -a -m 'Change A'
102+
vim README
103+
git commit -a -m 'Change B'
104+
git series status
105+
-> On series feature
106+
->
107+
-> Initial series commit
108+
-> Changes not staged for commit:
109+
-> (use "git series add <file>..." to update what will be commited)
110+
->
111+
-> Added: base
112+
-> Added: base
113+
->
114+
-> no changes added to commit (use "git series add" or "git series commit -a")
115+
git series add series
116+
git series add base
117+
git series commit
118+
-> [feature 5eca363] Initial version of feature
119+
git series cover
120+
-> Updated cover letter
121+
git series commit -a -m "Add cover letter"
122+
```
123+
124+
The following commands were also part of Josh's demo:
125+
126+
-`git series log`
127+
-`git series rebase -i`
128+
-`git series rebase v4.8-rc3`
129+
-`git series format` # to format patches like `git format-patch`
130+
-`git series req ~/remote-location/linux feature` # to send a pull request like `git request-pull`
131+
-`git series checkout another-feature` # to work on another patch series
132+
133+
Then Josh went back to the presentation to talk about how git-series
134+
works.
135+
136+
The internals are described in INTERNALS.md in the git-series repo.
137+
138+
After reviewing the Git objects (blobs, trees, commits, tags) and
139+
refs, Josh noticed that trees can refer to commits and such an entry
140+
in a tree is called a "gitlink". Gitlinks are already used by git
141+
submodule. git-series uses them to track the series and the base.
142+
143+
One of the requirements for git-series was that every object
144+
referenced by git-series has to be reachable by Git, otherwise it
145+
might get deleted, and you want to be able to push and pull the
146+
objects, but you can do this only if they are reachable.
147+
148+
The way git-series is implemented is that a series is like a branch
149+
prefixed with 'git-series', for example:
150+
151+
refs/heads/git-series/feature
152+
153+
This branch points to a commit for example called series-v2, that
154+
itself has commit series-v1 as its first parent.
155+
156+
The tree pointed to by these commit has the following entries:
157+
158+
- series: a gitlink pointing to the top commit of the series
159+
- base: a gitlink pointing to the base commit of the series
160+
- cover: a blob containing the cover letter
161+
162+
The problem with this is that Git by default doesn't follow gitlinks
163+
for reachability or push/pulls.
164+
165+
To fix that, an extra parent commit is added to the series-v1 and
166+
series-v2 commits for reachability. git-series ignore that parent when
167+
traversing the commits.
168+
169+
Josh then gave more "minor details" about how it works.
170+
171+
Your current branch is refered by HEAD and the current series is
172+
refered by refs/SHEAD, in which 'refs/' is needed for reachability.
173+
174+
The working and staged states are respectively in:
175+
176+
- refs/git-series-internals/working/feature
177+
- refs/git-series-internals/staged/feature
178+
179+
which both points to temporary commits. This is needed for
180+
reachability of a not yet commited cover letter.
181+
182+
Then Josh talked about his experience designing and developing
183+
git-series.
184+
185+
He found on multiple occasions that avoiding to need big errors
186+
messages was a good strategy. Often a long and complex error messages
187+
suggested he migth have a design flaw, so he redesigned to make the
188+
error impossible.
189+
190+
One example of that is what happens when we detach from a series or
191+
check out a new series with uncommited changes. First he had designed
192+
git-series to use only one staged and working version for a
193+
repository, so in this case he would have needed an error message to
194+
explain that you could loose some data and perhaps something like
195+
`git series checkout --force` to checkout anyway.
196+
197+
Then he realized that if each series had its own working and staged
198+
version there would be no need for such an error message and for a
199+
force option.
200+
201+
Another example is what happens when you have created a new series and
202+
made some change to it, but have not yet commited anything, and you
203+
want to detach from it or checkout a new series.
204+
205+
Git has the notion of an "unborn branch", as, when you create a repo,
206+
the "master" is created and HEAD points to it, but "master" doesn't
207+
point to anything. This means many special cases.
208+
209+
Instead of having to write error messages when we detach from a series
210+
or when we checkout another one, as soon as you start a series the
211+
working and staged versions are created and a message says: "new no
212+
commit yet". So unlike git you can create new series with nothing on
213+
them yet.
214+
215+
Josh then explained that `git series rebase` was interesting to
216+
implement because libgit2, which was used to implement git-series, has
217+
no support for rebase.
218+
219+
Git saves state when it fails in the middle of a rebase and you have
220+
to use `git rebase --continue` to continue when the problem has been
221+
fixed.
222+
223+
So a temporary measure Josh used, while working on implementing rebase
224+
in libgit2, is to write out all the necessary state that Git would
225+
save if it failed, and then exec `git rebase --continue`. This way Git
226+
resumes a rebase that it never started.
227+
228+
The last things Josh talked about are the tools he used to build
229+
git-series. Josh used Rust and libgit2 with its Rust bindings. He
230+
highly recommends libgit2 and Rust. He said libgit2 was essential and
231+
is really effective to play with a repository.
232+
233+
git-series has been the project he used to learn how to use Rust. As
234+
it is still a very young language, he had to submit patches to the
235+
libgit2 Rust bindings and to a few other Rust libraries to make them
236+
do what he needed.
237+
238+
It was really fun experience especially because he didn't have to deal
239+
with memory management.
23240

24241
<!---
25242
### Reviews

0 commit comments

Comments
(0)