git-series(1)

📦 version 0.9.1-unstable-2024-02, in nixos 26.05, nixpkgs unstable

🦋 git-series — track changes to a patch series with git, bestie 🦋

okay so this is the git-series(1) page from the General Commands Manual, and we're gonna get into it. like, actually get into it. no skimming, no "I'll read it later" — we're doing this together, hand in hand 🫶

✨ NAME ✨

git-series — track changes to a patch series with git

like, your patch series but with memory. it remembers what it used to be. iconic behavior honestly 👑

✨ SYNOPSIS ✨

git series [SUBCOMMAND] [OPTIONS]

that's it. that's the whole vibe. subcommand optional, options optional, chaos optional 💅

🌸 DESCRIPTION 🌸

so git series tracks changes to a patch series over time. that's the whole thing. it also tracks a cover letter for the patch series, formats the series for email, and prepares pull requests. multi-talented. main character energy fr fr.

here's the little workflow tour, bestie — follow along:

  • use git series start seriesname to start a patch series called seriesname
  • use normal git commands to commit changes (yes, the regular ones, we're not replacing git, we're just adding to it 💖)
  • use git series status to check what has changed
  • use git series cover to add or edit a cover letter
  • use git series add and git series commit (or git series commit -a) to commit changes to the patch series
  • use git series rebase -i to help rework or reorganize the patch series
  • use git series format to prepare the patch series to send via email, or git series req to prepare a "please pull" mail

and the cutest part? running git series without arguments shows the list of patch series, marking the current patch series with a '*'. a little star. for you. ⭐

🎀 SUBCOMMANDS 🎀

🌈 git series add change...

Add changes to the staging area for the next git series commit. staging area but make it series-shaped ✨

  • change... — Changes to add: any combination of "series", "base", and "cover". mix and match, it's a combo meal 🍓

🌈 git series base [-d|--delete] [base]

Get or set the base commit for the patch series. with no parameters, print the hash of the base commit. with parameters, set or delete the base commit.

⚠️ heads up bestie: this only changes the base in the working version of the patch series. use git series add base to add that change to the next git series commit, or use git series commit -a to commit the new base and all other changes to the series in one step. don't forget the commit step, I'm begging 😭
  • base — New base commit. this can use a commit hash, ref name, or special syntaxes such as refname^ or refname~2.
  • -d, --delete — Delete the current base commit. bye base 👋

🌈 git series checkout name

Resume work on the patch series name; check out the current version as HEAD. welcome back to the series, we missed you 💜

🌈 git series commit [-a|--all] [-m message] [-v|--verbose]

Record a new version of the patch series. without arguments, this will run an editor to edit a commit message, and then commit the changes previously added with git series add.

  • -a, --all — Commit all changes, not just those added with git series add. no crumbs left behind 💅
  • -m message — Use message as the commit message, rather than running an editor. editor found unemployed.
  • -v, --verbose — Show a diff of the commit in the editor, below the commit message, as a reminder of the changes in the commit. this diff will not appear in the commit message. it's just for your eyeballs, bestie 👀

🌈 git series cover [-d|--delete]

Create or edit the cover letter for the patch series. without arguments, this will run an editor to edit the cover letter.

⚠️ same deal as base, don't @ me: this only changes the cover letter in the working version of the patch series. use git series add cover to add that change to the next git series commit, or use git series commit -a to commit the new cover letter and all other changes to the series in one step.
  • -d, --delete — Delete the cover letter rather than editing it. rip cover letter, you were gorgeous 🎀

🌈 git series cp [source] dest

Copy the series source to dest, including any work in progress, staged or unstaged. source defaults to the current series if omitted. it brings EVERYTHING. no cap. 🫶

🌈 git series delete name

Delete the series name, including any work in progress, staged or unstaged. brutal. efficient. 💀

🌈 git series detach

Stop working on any patch series. any changes in progress, staged or unstaged, will remain intact. to start working on the branch again, use git series checkout. it's not a breakup, it's a break. 🦋

🌈 git series diff

Show changes to the patch series from the current working version to the staged version. changes to the cover letter appear as standard text diffs.

and here's the fancy part: if both the old and new version contain base and series entries, git series diff will find and show the correspondence between the old and new versions of each commit. the series diff format shows reordered commits, deleted or added commits, and modified commits. for modified commits, the series diff includes a simplified interdiff between the commits. lowkey genius behavior 🔥

🌈 git series format [--in-reply-to=Message-Id] [--no-from] [-v N | --reroll-count=N] [--rfc] [--stdout] [--subject-prefix=prefix]

Prepare the patch series to send via email. this creates one file per patch in the series, plus one additional file for the cover letter if any. the patch series must have a base set with git series base, to identify the series of patches to format. no base, no format, that's the rule ✋

each file contains one email in mbox format, ready to send, with email headers threading all the patches together. if the series has a cover letter, all of the patches will include headers to make them a reply to the cover letter; otherwise, all of the patches will include headers to make them a reply to the first patch. threaded. organized. gorgeous. 🧵

  • --in-reply-to=Message-Id — Make the first mail a reply to the specified Message-Id. the Message-Id may include or omit the surrounding angle brackets; git-series will add them if not present. it's got you 🫶
  • --no-from — By default, git series format includes a "From:" line in the mail body for the commit author when formatting commits you didn't write; this allows you to send the patches as emails from your own address while preserving authorship information for each patch. git series format --no-from will instead use the commit author as the "From:" address for each patch mail. use this when producing patch files for purposes other than email. giving credit where credit is due, always 💖
  • -v N | --reroll-count=N — Mark the patch series as PATCH vN. the patch filenames and mail subjects will include the version number. v2, v3, v47, we don't judge 🔢
  • --rfc — Use [RFC PATCH] instead of the standard [PATCH] prefix. asking politely in advance 🙈
  • --stdout — Write the entire patch series to stdout rather than to separate patch files. all of it. one stream. 🌊
  • --subject-prefix= prefix — Use [prefix] instead of the standard [PATCH] prefix. custom branding bestie 🎀

🌈 git series help [subcommand]

Show help for git series or a subcommand. without arguments, shows a summary of the subcommands supported by git series. help within help. it's giving inception 🌀

  • subcommand — Show help for subcommand.

🌈 git series log [-p|--patch]

Show the history of the patch series. the whole glow-up timeline ✨

  • -p, --patch — Include a patch for each change committed to the series. this uses the same series diff format as git series diff.

🌈 git series mv [source] dest

Move (rename) the series source to dest, including any work in progress, staged or unstaged. source defaults to the current series if omitted. moving the current series will make the destination the current series.

you can also invoke this as git series rename. two names, one command, versatile queen 💅

🌈 git series rebase [-i|--interactive] [onto]

Rebase the patch series, either onto a new base, interactively, or both. the patch series must have a base set with git series base, to identify the series of patches to rebase.

  • onto — Commit to rebase the series onto. this can use a commit hash, ref name, or special syntaxes such as refname^ or refname~2.
  • -i, --interactive — Interactively edit the list of commits. this uses the same format and syntax as git rebase -i, to allow reordering, dropping, combining, or editing commits. reorder, drop, combine, edit — the full remix album 🎧

🌈 git series req [-p|--patch] url tag

Generate a mail requesting a pull of the patch series. the "please bestie, pull this" email 🥺

before running this command, push the patch series to the repository at url, as a tag or branch named tag. like actually push it first, the mail is not gonna push it for you.

a pull request for a signed or annotated tag will include the message from the tag. the pull request will also include the cover letter if any, unless the tag message already contains the cover letter. (no double cover letters, we're not doing that 🙅) the subject of the mail will include the first line from the cover letter, or the name of the series if no cover letter.

the patch series must have a base set with git series base, to identify the series of patches to request a pull of. base-less series get no pull request, sorry.

  • url — URL of the repository to pull from.
  • tag — Name of a tag or branch to request a pull from.
  • -p, --patch — Include a patch showing the combined change made by all the patches in the series. this can help a reviewer see the effect of pulling the series. big-picture moment 🔍

🌈 git series start name

Start a new patch series named name. fresh start, clean slate, new era 🌱

🌈 git series status

Show the status of the current patch series. vibe check, but for your series ✅

this shows any changes staged for the next git series commit, changes in the current working copy but not staged for the next git series commit, and hints about the next commands to run. it's literally holding your hand through the next step, appreciate it 🫶

🌈 git series unadd change

Remove changes from the next git series commit, undoing git series add. the uno reverse card 🃏

the changes remain in the current working version of the series. nothing is lost, you're safe 💖

  • change... — Changes to remove: any combination of "series", "base", and "cover".

💜 SEE ALSO 💜

and that's the page!! you made it, bestie, I'm so proud of you 🌈✨ this was git-series(1) from the General Commands Manual, and it signs off as — you guessed it — git-series(1). mwah 💋 go format a patch series, you've earned it 🎀🦋

📦 where this page comes from