1.TH git-series 1
  2
  3.SH NAME
  4git-series \- track changes to a patch series with git
  5
  6.SH SYNOPSIS
  7.nf
  8\fBgit series\fR [\fISUBCOMMAND\fR] [\fIOPTIONS\fR]
  9.fi
 10
 11.SH DESCRIPTION
 12.PP
 13\fBgit series\fR tracks changes to a patch series over time.
 14\fBgit series\fR also tracks a cover letter for the patch series, formats the
 15series for email, and prepares pull requests.
 16
 17Use \fBgit series start\fR \fIseriesname\fR to start a patch series
 18\fIseriesname\fR.
 19Use normal \fBgit\fR commands to commit changes, and use \fBgit series
 20status\fR to check what has changed.
 21Use \fBgit series cover\fR to add or edit a cover letter.
 22Use \fBgit series add\fR and \fBgit series commit\fR (or \fBgit series commit
 23-a\fR) to commit changes to the patch series.
 24Use \fBgit series rebase -i\fR to help rework or reorganize the patch series.
 25Use \fBgit series format\fR to prepare the patch series to send via email, or
 26\fBgit series req\fR to prepare a "please pull" mail.
 27
 28Running \fBgit series\fR without arguments shows the list of patch series,
 29marking the current patch series with a '*'.
 30
 31.SH SUBCOMMANDS
 32.TP
 33\fBgit series add\fR \fIchange\fR...
 34Add changes to the staging area for the next \fBgit series commit\fR.
 35.RS
 36.TP
 37\fIchange\fR...
 38Changes to add: any combination of "series", "base", and "cover".
 39.RE
 40
 41.TP
 42\fBgit series base\fR [\fB-d\fR|\fB--delete\fR] [\fIbase\fR]
 43Get or set the base commit for the patch series.
 44With no parameters, print the hash of the base commit.
 45With parameters, set or delete the base commit.
 46
 47This only changes the base in the working version of the patch series; use
 48\fBgit series add base\fR to add that change to the next \fBgit series
 49commit\fR, or use \fBgit series commit -a\fR to commit the new base and all
 50other changes to the series in one step.
 51.RS
 52.TP
 53\fIbase\fR
 54New base commit.
 55This can use a commit hash, ref name, or special syntaxes such as refname^ or
 56refname~2.
 57.TP
 58.BR -d | --delete
 59Delete the current base commit.
 60.RE
 61
 62.TP
 63\fBgit series checkout\fR \fIname\fR
 64Resume work on the patch series \fIname\fR; check out the current version as
 65HEAD.
 66
 67.TP
 68\fBgit series commit\fR [\fB-a\fR|\fB--all\fR] [\fB-m\fR \fImessage\fR] \
 69[\fB-v\fR|\fB--verbose\fR]
 70Record a new version of the patch series.
 71Without arguments, this will run an editor to edit a commit message, and then
 72commit the changes previously added with \fBgit series add\fR.
 73.RS
 74.TP
 75.BR -a | --all
 76Commit all changes, not just those added with \fBgit series add\fR.
 77.TP
 78\fB-m\fR \fImessage\fR
 79Use \fImessage\fR as the commit message, rather than running an editor.
 80.TP
 81.BR -v | --verbose
 82Show a diff of the commit in the editor, below the commit message, as a
 83reminder of the changes in the commit.
 84This diff will not appear in the commit message.
 85.RE
 86
 87.TP
 88\fBgit series cover\fR [\fB-d\fR|\fB--delete\fR]
 89Create or edit the cover letter for the patch series.
 90Without arguments, this will run an editor to edit the cover letter.
 91
 92This only changes the cover letter in the working version of the patch series;
 93use \fBgit series add cover\fR to add that change to the next \fBgit series
 94commit\fR, or use \fBgit series commit -a\fR to commit the new cover letter and
 95all other changes to the series in one step.
 96.RS
 97.TP
 98.BR -d | --delete
 99Delete the cover letter rather than editing it.
100.RE
101
102.TP
103\fBgit series cp\fR [\fIsource\fR] \fIdest\fR
104Copy the series \fIsource\fR to \fIdest\fR, including any work in progress,
105staged or unstaged.
106\fIsource\fR defaults to the current series if omitted.
107
108.TP
109\fBgit series delete\fR \fIname\fR
110Delete the series \fIname\fR, including any work in progress, staged or unstaged.
111
112.TP
113\fBgit series detach\fR
114Stop working on any patch series.
115Any changes in progress, staged or unstaged, will remain intact.
116To start working on the branch again, use \fBgit series checkout\fR.
117
118.TP
119\fBgit series diff\fR
120Show changes to the patch series from the current working version to the staged
121version.
122Changes to the cover letter appear as standard text diffs.
123If both the old and new version contain base and series entries, \fBgit series
124diff\fR will find and show the correspondence between the old and new versions
125of each commit.
126The series diff format shows reordered commits, deleted or added commits, and
127modified commits.
128For modified commits, the series diff includes a simplified interdiff between
129the commits.
130
131.TP
132\fBgit series format\fR [\fB--in-reply-to=\fR\fIMessage-Id\fR] \
133[\fB--no-from\fR] \
134[\fB-v\fR \fIN\fR | \fB--reroll-count=\fR\fIN\fR] \
135[\fB--rfc\fR] \
136[\fB--stdout\fR] \
137[\fB--subject-prefix=\fR\fISubject-Prefix\fR]
138Prepare the patch series to send via email.
139This creates one file per patch in the series, plus one additional file for the
140cover letter if any.
141The patch series must have a base set with \fBgit series base\fR, to identify
142the series of patches to format.
143
144Each file contains one email in mbox format, ready to send, with email headers
145threading all the patches together.
146If the series has a cover letter, all of the patches will include headers to
147make them a reply to the cover letter; otherwise, all of the patches will
148include headers to make them a reply to the first patch.
149.RS
150.TP
151.BI --in-reply-to= Message-Id
152Make the first mail a reply to the specified Message-Id.
153The Message-Id may include or omit the surrounding angle brackets; git-series
154will add them if not present.
155.TP
156.B --no-from
157By default, \fBgit series format\fR includes a "From:" line in the mail body
158for the commit author when formatting commits you didn't write; this allows you
159to send the patches as emails from your own address while preserving authorship
160information for each patch.
161\fBgit series format --no-from\fR will instead use the commit author as the
162"From:" address for each patch mail.
163Use this when producing patch files for purposes other than email.
164.TP
165\fB-v\fR \fIN\fR | \fB--reroll-count=\fB\fIN\fR
166Mark the patch series as PATCH v\fIN\fR.
167The patch filenames and mail subjects will include the version number.
168.TP
169.B --rfc
170Use [RFC PATCH] instead of the standard [PATCH] prefix.
171.TP
172.B --stdout
173Write the entire patch series to stdout rather than to separate patch files.
174.TP
175.BI --subject-prefix= Subject-Prefix
176Use [\fISubject-Prefix\fR] instead of the standard [PATCH] prefix.
177.RE
178
179.TP
180\fBgit series help\fR [\fIsubcommand\fR]
181Show help for \fBgit series\fR or a subcommand.
182Without arguments, shows a summary of the subcommands supported by \fBgit
183series\fR.
184.RS
185.TP
186\fIsubcommand\fR
187Show help for \fIsubcommand\fR.
188.RE
189
190.TP
191\fBgit series log\fR [\fB-p\fR|\fB--patch\fR]
192Show the history of the patch series.
193.RS
194.TP
195.BR -p | --patch
196Include a patch for each change committed to the series.
197This uses the same series diff format as \fBgit series diff\fR.
198.RE
199
200.TP
201\fBgit series mv\fR [\fIsource\fR] \fIdest\fR
202Move (rename) the series \fIsource\fR to \fIdest\fR, including any work in
203progress, staged or unstaged.
204\fIsource\fR defaults to the current series if omitted.
205Moving the current series will make the destination the current series.
206
207You can also invoke this as \fBgit series rename\fR.
208
209.TP
210\fBgit series rebase\fR [\fB-i\fR|\fB--interactive\fR] [\fIonto\fR]
211Rebase the patch series, either onto a new base, interactively, or both.
212The patch series must have a base set with \fBgit series base\fR, to identify
213the series of patches to rebase.
214.RS
215.TP
216\fIonto\fR
217Commit to rebase the series onto.
218This can use a commit hash, ref name, or special syntaxes such as refname^ or
219refname~2.
220.TP
221.BR -i | --interactive
222Interactively edit the list of commits.
223This uses the same format and syntax as \fBgit rebase -i\fR, to allow
224reordering, dropping, combining, or editing commits.
225.RE
226
227.TP
228\fBgit series req\fR [\fB-p\fR|\fB--patch\fR] \fIurl\fR \fItag\fR
229Generate a mail requesting a pull of the patch series.
230
231Before running this command, push the patch series to the repository at
232\fIurl\fR, as a tag or branch named \fItag\fR.
233
234A pull request for a signed or annotated tag will include the message from the
235tag.  The pull request will also include the cover letter if any, unless the
236tag message already contains the cover letter.  The subject of the mail will
237include the first line from the cover letter, or the name of the series if no
238cover letter.
239
240The patch series must have a base set with \fBgit series base\fR, to identify
241the series of patches to request a pull of.
242.RS
243.TP
244\fIurl\fR
245URL of the repository to pull from.
246.TP
247.TP
248\fItag\fR
249Name of a tag or branch to request a pull from.
250.TP
251.BR -p | --patch
252Include a patch showing the combined change made by all the patches in the series.
253This can help a reviewer see the effect of pulling the series.
254.RE
255
256.TP
257\fBgit series start\fR \fIname\fR
258Start a new patch series named \fIname\fR.
259
260.TP
261\fBgit series status\fR
262Show the status of the current patch series.
263
264This shows any changes staged for the next \fBgit series commit\fR, changes in
265the current working copy but not staged for the next \fBgit series commit\fR,
266and hints about the next commands to run.
267
268.TP
269\fBgit series unadd\fR \fIchange\fR
270Remove changes from the next \fBgit series commit\fR, undoing \fBgit series
271add\fR.
272
273The changes remain in the current working version of the series.
274.RS
275.TP
276\fIchange\fR...
277Changes to remove: any combination of "series", "base", and "cover".
278.RE
279
280.SH "SEE ALSO"
281.BR git (1)