diff --git a/README.md b/README.md index b231937b3f37fdbeec5c0e76f06f1b9bf6ca42fc..f976f2bbfe27eea46877b0c03a63f53f574dbdca 100644 --- a/README.md +++ b/README.md @@ -51,8 +51,8 @@ change the `--root`. You may also want to install the included manpage, If you'd like to package git-series for your distribution, please contact me. -Getting started -=============== +Overview of commands +==================== - Use `git series start seriesname` to start a patch series seriesname. @@ -78,3 +78,83 @@ Getting started - Use `git series format` to prepare the patch series to send via email, or use `git series req` to prepare a "please pull" mail (after pushing the changes to a repository as a branch or tag). + +Workflow example +================ + +Suppose you want to write a patch series implementing a new feature for a +project. You already have a local `git clone` of the repository. You could +start a branch for this patch series, but it may take multiple iterations +before upstream accepts it, and you may need to use rebase or amend to fix +commits; a branch can't track that. With git-series, you'll develop the patch +series as you normally would, including rebases, and periodically `git series +commit` the state of the patch series, complete with a commit message +explaining what you've changed. Even if you rebase the patch series, or make +some other change that doesn't fast-forward, git-series will track those +changes with a branch that *does* fast-forward, so you can easily share and +review the history of your patch series. + +Developing or importing the first version +----------------------------------------- + +To start the patch series, first run `git series start featurename`. +`featurename` here specifies the name for the series, just as you'd specify the +name of a branch. + +A patch series needs some base to build on, identifying the upstream commit you +want to develop from. This will become the parent of the first patch in your +series. If you want to base your patch series on the current version, run `git +series base HEAD`. If you want to base this patch series on some other commit, +such as a released version, first check out that commit with `git checkout +thecommit`, then run `git series base HEAD`. + +You can then develop the patch series as usual, committing patches with git. + +If you've already started on the patch series and made some commits, you can +still adopt the current version of the patch series into git-series. Find the +parent commit of the first patch in your series, and run `git series base +thatcommit`. + +As with `git`, you can run `git series status` at any time to see the current +state of the series, including changes you might want to commit, and the next +step to run. After the above steps, `git series status` should show `base` and +`series` modified; running `git series base` set the `base` in the "working" +version, and `series` in the working version always refers to HEAD (the current +git commit you have checked out). + +Now that you've written an initial version of the patch series (or you already +wrote it before you started using git-series), you can commit that version to +git-series. Run `git series commit -a` to commit the series. This will run +your editor so you can provide a series commit message (e.g. "Initial version +of feature" or "Import feature into git-series"). + +If your patch series include multiple patches, you may want to add a cover +letter. Run `git series cover` to edit the cover letter, then `git series +commit -a -m 'Add cover letter'` to commit that change to the series. + +Now that you have the first version of the patch series, you can format it as a +series of emails with `git series format`. + +Developing v2 +------------- + +You send the patch series by email, and you get feedback from the maintainers: +the concept looks good, but you need to split one of the patches into two, and +add benchmark results in another commit's commit message. + +Run `git series rebase -i`, and split the commit (mark it for 'e'dit, `git +reset -N HEAD^`, repeatedly `git add -p` and `git commit`, then `git rebase +--continue`). Then, commit that change to the series: `git series commit -a -m +'Split out X change into a separate patch'` + +Then, run `git series rebase -i` again to add the benchmark results (mark the +commit for 'r'eword), and commit that change: `git series commit -a -m 'Add +benchmark results'`. + +You may want to document the changes in the cover letter: run `git series +cover`, document the changes, and `git series commit -a -m 'Update cover letter +for v2'`. (Alternatively, you can incrementally add to the cover letter along +with each change to the series.) + +Now that you have v2 of the patch series, you can format it as a new series of +emails with `git series format -v 2`.