Documentation/git-sequencer.txt

   1 git-sequencer(1)
   2 ================
   3
   4 NAME
   5 ----
   6 git-sequencer - Execute a sequence of git instructions
   7
   8 SYNOPSIS
   9 --------
  10 [verse]
  11 'git sequencer' [--batch] [--allow-dirty] [--verbose | --no-advice | --quiet]
  12                 [--] [<file>]
  13 'git sequencer' --continue | --skip | --abort
  14 'git sequencer' --edit | --status
  15
  16
  17 DESCRIPTION
  18 -----------
  19 Executes a sequence of git instructions to HEAD or `<base>`.
  20 The sequence is given by `<file>` or standard input.
  21 Also see 'TODO FILE FORMAT' below.
  22
  23 Before doing anything, the TODO file is checked for correct syntax
  24 and sanity.
  25
  26 In case of a conflict or request in the TODO file, 'git-sequencer' will
  27 pause. On conflict you can use 'git-diff' to locate the markers (`<<<<<<<`)
  28 and make edits to resolve the conflict.
  29
  30 For each file you edit, you need to tell git the changes by doing
  31
  32     git add <file>
  33
  34 After resolving the conflict manually and updating the index with the
  35 desired resolution, you can continue the sequencing process with
  36
  37     git sequencer --continue
  38
  39 Alternatively, you can undo the 'git-sequencer' progress with
  40
  41     git sequencer --abort
  42
  43 or skip the current instruction with
  44
  45     git sequencer --skip
  46
  47 or correct the TODO file with
  48
  49     git sequencer --edit
  50
  51 During pauses or when finished with the sequencing task, the current
  52 HEAD will always be the result of the last processed instruction.
  53
  54 Note that 'git-sequencer' detaches HEAD at the beginning.  That means,
  55 a commit that has been made by sequencer is not tracked by your initial
  56 branch until the sequencing process finishes successfully.
  57
  58
  59 OPTIONS
  60 -------
  61 <file>::
  62         Filename of the TODO file.  If omitted, standard input is used.
  63         See 'TODO FILE FORMAT' below.
  64
  65 --allow-dirty::
  66         Run even if working tree is dirty.
  67
  68 -B::
  69 --batch::
  70         Run in batch mode. If unexpected user intervention is needed
  71         (e.g. a conflict or the need to run an editor),
  72         'git-sequencer' aborts.
  73 +
  74 Note that the sanity check fails, if you use this option
  75 and an instruction like `edit` or `pause` is in the TODO file.
  76
  77 --continue::
  78         Restart the sequencing process after a pause.
  79
  80 --abort::
  81         Restore the original branch and abort the sequence operation.
  82
  83 --skip::
  84         Restart the sequencing process, skipping the current instruction.
  85
  86 --status::
  87         Show the current status of 'git-sequencer' and what
  88         operations can be done to change that status.
  89
  90 --edit::
  91         Invoke editor to edit the unprocessed part of the TODO file.
  92 +
  93 The file is syntax- and sanity-checked afterwards, so that you can
  94 safely run `git sequencer --skip` or `--continue` after editing.
  95 If you nonetheless noticed that you made a mistake, you can
  96 overwrite `.git/sequencer/todo` with `.git/sequencer/todo.old` and
  97 rerun `git sequencer --edit`.
  98 +
  99 If the check fails you are prompted if you want to correct your
 100 changes, edit again, cancel editing or really want to save.
 101
 102 --no-advice::
 103         Suppress advice on intentional and unintentional pauses.
 104
 105 -q::
 106 --quiet::
 107         Suppress output. Implies `--no-advice`.
 108
 109 -v::
 110 --verbose::
 111         Be more verbose.
 112
 113
 114 NOTES
 115 -----
 116
 117 'git-sequencer' will usually be called by other git commands, like
 118 linkgit:git-am[1] or linkgit:git-rebase[1].
 119
 120
 121 TODO FILE FORMAT
 122 ----------------
 123
 124 The TODO file contains one instruction per line.
 125
 126 Blank lines will be ignored.
 127 All characters after a `#` character are comments and will be ignored until
 128 the end of a line.
 129
 130 The following instructions can be used:
 131
 132
 133 noop::
 134         Do nothing.
 135 +
 136 This is useful if you want 'git-sequencer' to do nothing with zero
 137 exit status (success).
 138
 139
 140 pick [options] <commit>::
 141         Pick (see linkgit:git-cherry-pick[1]) a commit.
 142         Sequencer will pause on conflicts.
 143 +
 144 See the following list and 'GENERAL OPTIONS' for values of `options`:
 145
 146         -R;;
 147         --reverse;;
 148                 Revert the changes introduced by pick <commit>.
 149
 150         --mainline=<n>;;
 151                 Allow you to pick merge commits by specifying the
 152                 parent number (beginning from 1) to let sequencer
 153                 replay the changes relative to the specified parent.
 154
 155
 156 patch [options] <file>::
 157         If file `<file>` is a pure (diff) patch, then apply the patch.
 158         If no `--message` option is given, an editor will
 159         be invoked to enter a commit message.
 160 +
 161 If `<file>` is a linkgit:git-format-patch[1]-formatted patch,
 162 then the patch will be commited.
 163 +
 164 See the following list and 'GENERAL OPTIONS' for values of `options`:
 165
 166         -3;;
 167         --3way;;
 168                 When the patch does not apply cleanly, fall back on
 169                 3-way merge, if the patch records the identity of blobs
 170                 it is supposed to apply to, and we have those blobs
 171                 available locally.
 172
 173         -k;;
 174                 Pass `-k` flag to 'git-mailinfo' (see linkgit:git-mailinfo[1]).
 175
 176         -n;;
 177                 Pass `-n` flag to 'git-mailinfo' (see linkgit:git-mailinfo[1]).
 178
 179 And the following options, that will be passed to 'git-apply':
 180
 181         --exclude=<path-pattern>;;
 182                 Do not apply changes to files matching the given path pattern.
 183                 This can be useful when importing patchsets, where you want to
 184                 exclude certain files or directories.
 185
 186         -R;;
 187         --reverse;;
 188                 Apply the patch in reverse.
 189
 190         --no-add;;
 191                 When applying a patch, ignore additions made by the
 192                 patch.  This can be used to extract the common part between
 193                 two files by first running 'diff' on them and applying
 194                 the result with this option, which would apply the
 195                 deletion part but not addition part.
 196
 197         --whitespace=<action>;;
 198                 Specify behavior on whitespace errors.
 199                 See linkgit:git-apply[1] for a detailed description.
 200
 201         --context=<n>;;
 202                 Ensure at least <n> lines of surrounding context match before
 203                 and after each change.  When fewer lines of surrounding
 204                 context exist they all must match.  By default no context is
 205                 ever ignored.
 206
 207         --inaccurate-eof;;
 208                 Under certain circumstances, some versions of 'diff' do not
 209                 correctly detect a missing new-line at the end of the file.
 210                 As a result, patches created by such 'diff' programs do not
 211                 record incomplete lines correctly.
 212                 This option adds support for applying such patches by
 213                 working around this bug.
 214
 215         -p<n>;;
 216                 Remove <n> leading slashes from traditional diff paths.
 217                 The default is 1.
 218
 219         --unidiff-zero;;
 220                 By default, 'git-apply' expects that the patch being
 221                 applied is a unified diff with at least one line of context.
 222                 This provides good safety measures, but breaks down when
 223                 applying a diff generated with --unified=0. To bypass these
 224                 checks use this option.
 225
 226         --recount;;
 227                 Do not trust the line counts in the hunk headers, but infer them
 228                 by inspecting the patch (e.g. after editing the patch without
 229                 adjusting the hunk headers appropriately).
 230
 231         --directory=<root>;;
 232                 Prepend <root> to all filenames.  If a "-p" argument was passed,
 233                 too, it is applied before prepending the new root.
 234
 235
 236 pause::
 237         Pause the sequencer process to let you manually make changes.
 238         For example, you can re-edit the done commit, split a commit,
 239         fix bugs or typos, or make further commits on top of HEAD before
 240         continuing.
 241 +
 242 After you have finished your changes and added them to the index,
 243 invoke `git sequencer --continue`.
 244 If you only want to edit the last commit message with an editor,
 245 run `git commit --amend` (see linkgit:git-commit[1]) before saying
 246 `--continue`.
 247
 248
 249 edit <commit>::
 250         Pick a commit and pause the sequencer process to let you
 251         make changes.
 252 +
 253 This is a short form for `pick <commit> and `pause` on separate lines.
 254
 255
 256 mark <mark>::
 257         Set a symbolic mark for the last commit.
 258         `<mark>` is an unsigned integer starting at 1 and
 259         prefixed with a colon, e.g. `:1`.
 260 +
 261 The marks can help if you want to refer to commits that you
 262 created during the sequencer process, e.g. if you want to
 263 merge such a commit.
 264 +
 265 The set marks are removed after the sequencer has completed.
 266
 267
 268 reset <commit-ish>::
 269         Go back (see linkgit:git-reset[1] `--hard`) to commit `<commit-ish>`.
 270         `<commit-ish>` can also be given by a mark, if prefixed with a colon.
 271
 272
 273 merge [options] <commit-ish1> <commit-ish2> ... <commit-ishN>::
 274         Merge commits into HEAD.
 275 +
 276 You can refer to a commit by a mark.
 277 +
 278 If you do not provide a commit message (using `-F`, `-m`, `-C`, `-M`,
 279 or `--standard`), an editor will be invoked.
 280 +
 281 See the following list and 'GENERAL OPTIONS' for values of `options`:
 282
 283         --standard;;
 284                 Append a commit message like 'Merge ... into HEAD'.
 285                 See also linkgit:git-fmt-merge-msg[1].
 286
 287         -s <strategy>;;
 288         --strategy=<strategy>;;
 289                 Use the given merge strategy.
 290                 See also linkgit:git-merge[1].
 291
 292
 293 ref <ref>::
 294         Set ref `<ref>` to the current HEAD, see also
 295         linkgit:git-update-ref[1].
 296
 297
 298 squash [options] <commit>::
 299         Add the changes introduced by `<commit>` to the last commit.
 300 +
 301 See 'GENERAL OPTIONS' for values of `options`.
 302
 303 squash [options] --from <mark>::
 304         Squash all commits from the given mark into one commit.
 305         There must not be any `merge` instructions between the
 306         `mark` instruction and this `squash --from` instruction.
 307 +
 308 See the following list and 'GENERAL OPTIONS' for values of `options`:
 309
 310         --include-merges;;
 311                 Sanity check does not fail if you have merges
 312                 between HEAD and <mark>.
 313
 314
 315 run [--directory=<path>] [--] <cmd> <args>...::
 316         Run command `<cmd>` with arguments `<args>`.
 317         Pause (conflict-like) if exit status is non-zero.
 318 +
 319 If `<path>` is set, sequencer will change directory to `<path>`
 320 before running the command and change back after exit.
 321
 322
 323 GENERAL OPTIONS
 324 ---------------
 325
 326 Besides some special options, the instructions
 327 `merge`, `patch`, `pick`, `squash` take the following general options:
 328
 329 --author=<author>::
 330         Override the author name and e-mail address used in the commit.
 331         Use `A U Thor <author@example.com>` format.
 332
 333 -C <commit-ish>::
 334 --reuse-commit=<commit-ish>::
 335         Reuse message and authorship data from specified commit.
 336
 337 -M <commit-ish>
 338 --reuse-message=<commit-ish>::
 339         Reuse message from specified commit.
 340         Note that only the commit message is reused
 341         and not the authorship information.
 342
 343 -F <file>::
 344 --file=<file>::
 345         Take the commit message from the given file.
 346
 347 -m <msg>::
 348 --message=<msg>::
 349         Use the given `<msg>` as the commit message.
 350
 351 --signoff::
 352         Add `Signed-off-by:` line to the commit message (if not yet there),
 353         using the committer identity of yourself.
 354
 355 -e::
 356 --edit::
 357         Regardless what commit message options are given,
 358         invoke the editor to allow editing of the commit message.
 359
 360
 361 EXIT STATUS
 362 -----------
 363
 364 'git-sequencer' returns:
 365
 366 * `0`, if 'git-sequencer' successfully completed all the instructions
 367        in the TODO file or successfully aborted after
 368        `git sequencer --abort`,
 369 * `2`, on user-requested pausing, e.g.
 370        when using the `edit` instruction.
 371 * `3`, on pauses that are not requested, e.g.
 372        when there are conflicts to resolve
 373        or errors in the TODO file.
 374 * any other value on error, e.g.
 375   running 'git-sequencer' on a bare repository.
 376
 377
 378 FILES
 379 -----
 380
 381 'git-sequencer' is writing information into `$GIT_DIR/sequencer/`.
 382
 383 The file `$GIT_DIR/sequencer/patch` is generated on conflict so
 384 that the user can inspect the original patch.
 385
 386 The file `$GIT_DIR/sequencer/todo.old` is generated by
 387 `git sequencer --edit` and can be used to overwrite
 388 `$GIT_DIR/sequencer/todo` if things are messed up after editing.
 389
 390 All other files in this directory should not be touched directly.
 391
 392
 393 EXAMPLES
 394 --------
 395
 396 Here are some examples that shall ease the start with the TODO
 397 file format.
 398
 399 Manually editing and adding commits
 400 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 401
 402 Sequencer allows manual intervention in between.
 403 This can be useful to
 404
 405 * check if everything has gone right so far,
 406
 407 * split commits,
 408
 409 * edit changes and/or commit messages, or
 410
 411 * add further manual commits on top of the current one.
 412
 413 If you want to do one of this, either change `pick` to `edit`, or
 414 add a `pause` line after the specific instruction.
 415
 416 Note that if you only want to edit the commit message in an
 417 editor, just use the `--edit` option of your `pick` or `patch`
 418 instruction.
 419
 420 `HEAD` refers to the last commit being done by sequencer.
 421 So if you want to split a commit, repeat something like
 422
 423 ------------
 424 $ git reset HEAD^   # Reset index to HEAD^, but keep working tree
 425                     # HEAD is the last commit being done by sequencer
 426 $ git add -p        # Add changes interactively to the index, and/or
 427 $ git add file1     # Add changes from file1 to the index
 428 $ git commit        # Commit staged changes
 429 ------------
 430
 431 until you have no changes to commit, and then run
 432
 433 ------------
 434 $ git sequencer --continue   # Continue sequencer process
 435 ------------
 436
 437
 438 Squashing commits
 439 ~~~~~~~~~~~~~~~~~
 440
 441 Squashing commits means putting the changes of many commits into one.
 442 If you have two commits `abcdef1` and `fa1afe1` and you want to squash them,
 443 feed 'git-sequencer' with a TODO file like:
 444
 445 ------------
 446 pick abcdef1
 447 squash fa1afe1
 448 ------------
 449
 450 Squash will concatenate the commit messages of `abcdef1` and `fa1afe1` and
 451 invoke an editor so that you can edit them.
 452 Perhaps you just want to reuse the commit message of `abcdef1` and
 453 add a signoff.  Then use:
 454
 455 ------------
 456 pick abcdef1
 457 squash -C abcdef1 --signoff fa1afe1
 458 ------------
 459
 460 You can also squash more than two commits.
 461 Basically you can do:
 462
 463 ------------
 464 pick A
 465 squash B
 466 squash C
 467 squash D
 468 squash --message "Make indentation consistent" --signoff E
 469 ------------
 470
 471 If somebody sent you a patch that you have not yet applied and you want
 472 to apply it and squash it, or if you have a `pick <commit>` list generated
 473 with something like
 474
 475 ------------
 476 $ git log --pretty=format:'pick %h  # %s' --no-merges --reverse A^..E
 477 ------------
 478
 479 you can use the `mark` and `squash --from` instructions to
 480 squash all commits between them into one:
 481
 482 ------------
 483 mark :0
 484 pick A
 485 pick B
 486 pick C
 487 pick D
 488 pick E
 489 squash --message "Make indentation consistent" --signoff --from :0
 490 ------------
 491
 492
 493 Branching and Merging
 494 ~~~~~~~~~~~~~~~~~~~~~
 495
 496 Merging branches can easily be done using the `merge` instruction.
 497 For an example, it is more interesting to branch, pick some commits
 498 and merge.  Imagine you want to 'copy' this onto the current branch:
 499
 500 ------------
 501  ...--A1--A2--A3--A4--A5---MA-A6  refs/heads/old
 502        |       \          /
 503        |        C1--MC--C2  refs/heads/topic
 504         \          /
 505          B1--B2--B3
 506 ------------
 507
 508 You want the copy to look exactly like this, except that you
 509 are not on branch `old`, and you want to call the copy of `topic`
 510 simply `topic2`.
 511 Here is a way to achieve this:
 512
 513 ------------
 514 pick A1
 515 mark :0    # remember this to pick further commits on trunk A
 516
 517 pick B1    # pick commits for trunk B
 518 pick B2
 519 pick B3
 520 mark :1    # remember this for merge
 521 # Why not just merge B3 later?
 522 # Then you would merge the original B3 and not the copy.
 523 # But in this example you want to merge the copy of B3.
 524
 525 reset :0   # go back to the copy of A1
 526 pick A2    # go on picking the commits of trunk A
 527 pick A3
 528 mark :2    # remember this to pick further commits on trunk A
 529
 530 pick C1    # pick commits for trunk C
 531 merge -C MC :1    # merge trunk B
 532 pick C2
 533 ref refs/heads/topic2    # create branch for the C trunk
 534
 535 reset :2   # go back to last commit of trunk A (copy of A3)
 536 pick A4    # go on picking the commits of trunk A
 537 pick A5
 538 merge --standard topic2   # merge trunk C
 539 pick A6
 540 ------------
 541
 542
 543 Proper handling of conflicts
 544 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 545
 546 First of all, you are encouraged to use linkgit:git-rerere[1]:
 547
 548 ------------
 549 $ git config rerere.enabled true    # enable rerere
 550 ------------
 551
 552 Sequencer invokes 'git-rerere' automatically on conflict.
 553
 554 If you experience conflicts, try
 555
 556 ------------
 557 $ git diff     # Show conflicting code
 558 $ git status   # Show conflicting files
 559 ------------
 560
 561 Then fix these conflicts using your editor and run
 562
 563 ------------
 564 $ git add file1 file2 file3   # Add modified files to the index
 565 $ git status                  # Make sure working tree is clean
 566 $ git sequencer --continue    # Continue sequencer process
 567 ------------
 568
 569 Now assume a conflict happens because you have unproperly edited
 570 the TODO file.
 571
 572 Imagine your initial TODO file was:
 573
 574 ------------
 575 pick A
 576 pick C
 577 pick D
 578 ------------
 579
 580 But you wanted to pick B before C, and now you have this conflict on
 581 picking C.  You may first have a look at:
 582
 583 ------------
 584 $ git sequencer --status
 585 ------------
 586
 587 This will show you, what has been done, in what step the conflict
 588 happened and what is still to do, like this:
 589
 590 ------------
 591 Already done (or tried):
 592   pick A
 593   pick C
 594
 595 Interrupted by conflict at
 596   pick C
 597
 598 Still to do:
 599   pick D
 600
 601 To abort & restore, invoke:
 602     git sequencer --abort
 603 To continue, invoke:
 604     git sequencer --continue
 605 To skip the current instruction, invoke:
 606     git sequencer --skip
 607 ------------
 608
 609 A good way to solve that situation is running
 610
 611 ------------
 612 $ git sequencer --edit
 613 ------------
 614
 615 and change the file to:
 616
 617 ------------
 618 pick B
 619 pick C
 620 pick D
 621 ------------
 622
 623 Save the file, and invoke:
 624
 625 ------------
 626 $ git sequencer --skip
 627 ------------
 628
 629 Then the conflict-ridden `pick C` will be skipped and B is picked,
 630 before C will again be picked.
 631
 632
 633 Running tests
 634 ~~~~~~~~~~~~~
 635
 636 Imagine you have test programs within a `tests/` directory in your working
 637 tree.  But before running your test programs, you have to invoke `make` in
 638 the root directory of the working tree to compile your project.
 639
 640 If the commit policy of your project says that after every commit the
 641 software must be able to compile and the test suite must pass, you
 642 are required to check this after every pick.
 643
 644 This example shows how 'git-sequencer' can assist you:
 645
 646 ------------
 647 pick A      # Fix foo
 648 run make
 649 run --directory=tests ./test-foo
 650 pick B      # Extend bar
 651 run make
 652 run --directory tests -- ./test-bar --expensive-tests
 653 pick C
 654 run make
 655 run --directory tests make tests
 656 ------------
 657
 658 Sequencer will be paused, when a run fails (i.e. on non-zero exit status).
 659 Then it is your turn to fix the problem and make the tests pass.
 660
 661 Note that on `git sequencer --continue`, 'git-sequencer' will not
 662 repeat the failed `run` instruction.
 663
 664
 665 SEE ALSO
 666 --------
 667
 668 linkgit:git-add[1],
 669 linkgit:git-am[1],
 670 linkgit:git-cherry-pick[1],
 671 linkgit:git-commit[1],
 672 linkgit:git-fmt-merge-msg[1],
 673 linkgit:git-format-patch[1],
 674 linkgit:git-rebase[1],
 675 linkgit:git-rerere[1],
 676 linkgit:git-reset[1],
 677 linkgit:git-update-ref[1]
 678
 679
 680 Authors
 681 -------
 682 Written by Stephan Beyer <s-beyer@gmx.net>.
 683
 684
 685 Documentation
 686 -------------
 687 Documentation by Stephan Beyer and the git-list <git@vger.kernel.org>.
 688
 689 GIT
 690 ---
 691 Part of the linkgit:git[1] suite