1git series tracks changes to a patch series over time. git series also tracks
2a cover letter for the patch series, formats the series for email, and prepares
3pull requests.
4
5[Manpage for git-series](http://man7.org/linux/man-pages/man1/git-series.1.html)
6
7About git-series
8================
9
10A patch series typically goes through multiple iterations before submission;
11the path from idea to RFC to `[PATCHv12 1/8]` includes many invocations of
12`git rebase -i`. However, while Git tracks and organizes commits quite well, it
13doesn't actually track changes to a patch series at all, outside of the
14ephemeral reflog. This makes it a challenge to collaborate on a patch series,
15distribution package, backport, or any other development process that includes
16rebasing or non-fast-forward development.
17
18Typically, tracking the evolution of a patch series over time involves moving
19part of the version control outside of git. You can move the patch series from
20git into quilt or a distribution package, and then version the patch files with
21git, losing the power of git's tools. Or, you can keep the patch series in
22git, and version it via multiple named branches; however, names like
23feature-v2, feature-v3-typofix, and feature-v8-rebased-4.6-alice-fix sound like
24filenames from corporate email, not modern version control. And either way,
25git doesn't track your cover letter at all.
26
27git-series tracks both a patch series and its evolution within the same git
28repository. git-series works entirely with existing git features, allowing git
29to push and pull a series to any git repository along with other branches and
30tags. git-series also tracks a cover letter for the patch series, formats the
31series for email, and prepares pull requests.
32
33As you change a patch series, git-series can show diffs between versions,
34finding and showing the correspondence between the old and new versions of each
35commit, even after changing or rebasing those commits. The series diff format
36shows corresponding old and new commits side-by-side, with interdiffs for
37modified commits. (This is similar to the `git range-diff` format.)
38
39Building and installing
40=======================
41
42git-series is written in Rust. You'll need both Rust and Cargo installed to
43build it. If your OS distribution includes packages for Rust and Cargo, start
44by installing those (for instance, on Debian, `apt install rustc cargo`).
45If your distribution doesn't have packages of Rust and Cargo, or has an
46outdated version (which may result in build errors), you can [download the
47stable version of Rust and Cargo from the rust-lang.org download
48page](https://www.rust-lang.org/downloads.html).
49
50With Rust and Cargo installed, you can download and install the latest release
51of git-series with:
52
53```
54cargo install --root ~/.local git-series
55```
56
57This will install git-series into `~/.local/bin/git-series`. If you don't
58already have `~/.local/bin` on your `$PATH`, you may want to add it there, or
59change the `--root`. You may also want to install the included manpage,
60`git-series.1`, into `~/.local/share/man/man1/git-series.1`.
61
62If you'd like to package git-series for your distribution, please contact me.
63
64Overview of commands
65====================
66
67- Use `git series start seriesname` to start a patch series seriesname.
68
69- Use `git series base somecommit` to set the base commit for the series.
70 (This is the upstream commit you based the series on, not the first patch in
71 the series.)
72
73- Use normal git commands to commit changes.
74
75- Use `git series rebase -i` to help rework or reorganize the patch series.
76
77- Use `git series status` to check what has changed.
78
79- Use `git series diff` to show the changes to the patch series as a diff.
80
81- Use `git series cover` to add or edit a cover letter.
82
83- Use `git series add` and `git series commit` (or `git series commit -a`) to
84 commit changes to the patch series. You can do this whenever you've changed
85 the base or cover letter, or whenever you've changed HEAD to a new commit.
86 Make a series commit whenever you've made a semantic change to the patch
87 series that you want to record, such as rebasing on a new upstream version,
88 reorganizing patches, or incorporating feedback.
89
90- Use `git series format` to prepare the patch series to send via email, or
91 use `git series req` to prepare a "please pull" mail (after pushing the
92 changes to a repository as a branch or tag).
93
94Workflow example
95================
96
97Suppose you want to write a patch series implementing a new feature for a
98project. You already have a local `git clone` of the repository. You could
99start a branch for this patch series, but it may take multiple iterations
100before upstream accepts it, and you may need to use rebase or amend to fix
101commits; a branch can't track that. With git-series, you'll develop the patch
102series as you normally would, including rebases, and periodically `git series
103commit` the state of the patch series, complete with a commit message
104explaining what you've changed. Even if you rebase the patch series, or make
105some other change that doesn't fast-forward, git-series will track those
106changes with a branch that *does* fast-forward, so you can easily share and
107review the history of your patch series.
108
109Developing or importing the first version
110-----------------------------------------
111
112To start the patch series, first run `git series start featurename`.
113`featurename` here specifies the name for the series, just as you'd specify the
114name of a branch.
115
116A patch series needs some base to build on, identifying the upstream commit you
117want to develop from. This will become the parent of the first patch in your
118series. If you want to base your patch series on the current version, run `git
119series base HEAD`. If you want to base this patch series on some other commit,
120such as a released version, first check out that commit with `git checkout
121thecommit`, then run `git series base HEAD`.
122
123You can then develop the patch series as usual, committing patches with git.
124
125If you've already started on the patch series and made some commits, you can
126still adopt the current version of the patch series into git-series. Find the
127parent commit of the first patch in your series, and run `git series base
128thatcommit`.
129
130As with `git`, you can run `git series status` at any time to see the current
131state of the series, including changes you might want to commit, and the next
132step to run. After the above steps, `git series status` should show `base` and
133`series` modified; running `git series base` set the `base` in the "working"
134version, and `series` in the working version always refers to HEAD (the current
135git commit you have checked out).
136
137Now that you've written an initial version of the patch series (or you already
138wrote it before you started using git-series), you can commit that version to
139git-series. Run `git series commit -a` to commit the series. This will run
140your editor so you can provide a series commit message (e.g. "Initial version
141of feature" or "Import feature into git-series").
142
143If your patch series include multiple patches, you may want to add a cover
144letter. Run `git series cover` to edit the cover letter, then `git series
145commit -a -m 'Add cover letter'` to commit that change to the series.
146
147Now that you have the first version of the patch series, you can format it as a
148series of emails with `git series format`.
149
150Developing v2
151-------------
152
153You send the patch series by email, and you get feedback from the maintainers:
154the concept looks good, but you need to split one of the patches into two, and
155add benchmark results in another commit's commit message.
156
157Run `git series rebase -i`, and split the commit (mark it for 'e'dit, `git
158reset -N HEAD^`, repeatedly `git add -p` and `git commit`, then `git rebase
159--continue`). Then, commit that change to the series: `git series commit -a -m
160'Split out X change into a separate patch'`
161
162Then, run `git series rebase -i` again to add the benchmark results (mark the
163commit for 'r'eword), and commit that change: `git series commit -a -m 'Add
164benchmark results'`.
165
166You may want to document the changes in the cover letter: run `git series
167cover`, document the changes, and `git series commit -a -m 'Update cover letter
168for v2'`. (Alternatively, you can incrementally add to the cover letter along
169with each change to the series.)
170
171Now that you have v2 of the patch series, you can format it as a new series of
172emails with `git series format -v 2`.