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
 5About git-series
 6================
 7
 8A patch series typically goes through multiple iterations before submission;
 9the path from idea to RFC to `[PATCHv12 1/8]` includes many invocations of
10`git rebase -i`. However, while Git tracks and organizes commits quite well, it
11doesn't actually track changes to a patch series at all, outside of the
12ephemeral reflog.  This makes it a challenge to collaborate on a patch series,
13distribution package, backport, or any other development process that includes
14rebasing or non-fast-forward development.
15
16Typically, tracking the evolution of a patch series over time involves moving
17part of the version control outside of git.  You can move the patch series from
18git into quilt or a distribution package, and then version the patch files with
19git, losing the power of git's tools.  Or, you can keep the patch series in
20git, and version it via multiple named branches; however, names like
21feature-v2, feature-v3-typofix, and feature-v8-rebased-4.6-alice-fix sound like
22filenames from corporate email, not modern version control.  And either way,
23git doesn't track your cover letter at all.
24
25git-series tracks both a patch series and its evolution within the same git
26repository.  git-series works entirely with existing git features, allowing git
27to push and pull a series to any git repository along with other branches and
28tags.  git-series also tracks a cover letter for the patch series, formats the
29series for email, and prepares pull requests.
30
31Building and installing
32=======================
33
34git-series is written in Rust.  You'll need both Rust and Cargo installed to
35build it.  If your OS distribution includes packages for Rust and Cargo, start
36by installing those (for instance, on Debian, `apt install rustc cargo`).
37Otherwise, you can [download the stable version of Rust and Cargo from the
38rust-lang.org download page](https://www.rust-lang.org/downloads.html).
39
40With Rust and Cargo installed, you can download and install the latest release
41of git-series with:
42
43```
44cargo install --root ~/.local git-series
45```
46
47This will install git-series into `~/.local/bin/git-series`.  If you don't
48already have `~/.local/bin` on your `$PATH`, you may want to add it there, or
49change the `--root`.  You may also want to install the included manpage,
50`git-series.1`, into `~/.local/share/man/man1/git-series.1`.
51
52If you'd like to package git-series for your distribution, please contact me.
53
54Getting started
55===============
56
57- Use `git series start seriesname` to start a patch series seriesname.
58
59- Use `git series base somecommit` to set the base commit for the series.
60  (This is the upstream commit you based the series on, not the first patch in
61  the series.)
62
63- Use normal git commands to commit changes.
64
65- Use `git series status` to check what has changed.
66
67- Use `git series cover` to add or edit a cover letter.
68
69- Use `git series add` and `git series commit` (or `git series commit -a`) to
70  commit changes to the patch series.
71
72- Use `git series rebase -i` to help rework or reorganize the patch series.
73
74- Use `git series format` to prepare the patch series to send via email, or
75  use `git series req` to prepare a "please pull" mail (after pushing the
76  changes to a repository as a branch or tag).