Hi, > I inline-attached the documentation (and somehow specification) > for git-sequencer (my GSoC'08 project) for you to comment on. Here's the second and - if there are no big protests - last attempt before I send the prototype RFC/PATCH patchset to the list. Note that I didn't add the "comment" (or "amend") insn[1] proposed by Pierre Habouzit currently, but this is no problem. 1. http://thread.gmane.org/gmane.comp.version-control.git/84616 There's also an undocumented --caller option. I mean, it is as undocumented as "git-am --rebasing", because it should only be used by sequencer user scripts. Regards, Stephan ------------------------------ git-sequencer.txt ------------------------------ git-sequencer(1) ================ NAME ---- git-sequencer - Execute a sequence of git instructions SYNOPSIS -------- [verse] 'git-sequencer' [--batch] [--onto=<base>] [--verbose] [<file>] 'git-sequencer' --continue | --skip | --abort | --edit | --status DESCRIPTION ----------- Executes a sequence of git instructions to HEAD or `<base>`. The sequence is given by `<file>` or standard input. Also see 'TODO FILE FORMAT' below. Before doing anything, the TODO file is checked for correct syntax and sanity. In case of a conflict or request in the TODO file, git-sequencer will pause. On conflict you can use git-diff to locate the markers (`<<<<<<`) and make edits to resolve the conflict. For each file you edit, you need to tell git the changes by doing git add <file> After resolving the conflict manually and updating the index with the desired resolution, you can continue the sequencing process with git sequencer --continue Alternatively, you can undo the git-sequencer progress with git sequencer --abort or skip the current instruction with git sequencer --skip or correct the TODO file with git sequencer --edit During pauses or when finished with the sequencing task, the current HEAD will always be the result of the last processed instruction. OPTIONS ------- <file>:: Filename of the TODO file. If omitted, standard input is used. See 'TODO FILE FORMAT' below. -B:: --batch:: Run in batch mode. If unexpected user intervention is needed (e.g. a conflict or the need to run an editor), git-sequencer fails. + Note that the sanity check fails, if you use this option and an instruction like `edit` or `pause`. --onto=<base>:: Checkout given commit or branch before sequencing. If you provide a branch, sequencer will make the provided changes on the branch, i.e. the branch will be changed. --continue:: Restart the sequencing process after having resolved a merge conflict. --abort:: Restore the original branch and abort the sequence operation. --skip:: Restart the sequencing process by skipping the current patch. --status:: Show the current status of git-sequencer and what operations can be done to change that status. --edit:: Invoke editor to edit the undone rest of the TODO file. + The file is syntax- and sanity-checked afterwards, so that you can safely run `git sequencer --skip` or `--continue` after editing. If you nonetheless noticed that you made a mistake, you can overwrite `.git/sequencer/todo` with `.git/sequencer/todo.old` and rerun `git sequencer --edit`. + If the check fails you are prompted if you want to correct your changes, edit again, cancel editing or really want to save. -v:: --verbose:: Be more verbose. [XXX: to be defined more accurately, i.e. print diffstat] NOTES ----- When sequencing, it is possible, that you are changing the history of a branch in a way that can cause problems for anyone who already has a copy of the branch in their repository and tries to pull updates from you. You should understand the implications of using git-sequencer on a repository that you share. git-sequencer will usually be called by another git porcelain, like linkgit:git-am[1] or linkgit:git-rebase[1]. TODO FILE FORMAT ---------------- The TODO file contains basically one instruction per line. Blank lines will be ignored. All characters after a `#` character will be ignored until the end of a line. The following instructions can be used: edit <commit>:: Picks a commit and pauses the sequencer process to let you make changes. + This is a short form for `pick <commit> and `pause` on separate lines. mark <mark>:: Set a symbolic mark for the last commit. `<mark>` is an unsigned integer starting at 1 and prefixed with a colon, e.g. `:1`. + The marks can help if you want to refer to commits that you created during the sequencer process, e.g. if you want to merge such a commit. + The set marks are removed after the sequencer has completed. merge [<options>] <commit-ish1> <commit-ish2> ... <commit-ishN>:: Merge commits into HEAD. + A commit can also be given by a mark, if prefixed with a colon. + If you do not provide a commit message (using `-F`, `-m`, `--reference` or `--standard`), an editor will be invoked. + See the following list and 'GENERAL OPTIONS' for values of `<option>`: --standard;; Generates a commit message like 'Merge ... into HEAD'. See also linkgit:git-fmt-merge-msg[1]. -s <strategy>;; --strategy=<strategy>;; Use the given merge strategy. See also linkgit:git-merge[1]. pick [<options>] <commit>:: Pick (see linkgit:git-cherry-pick[1]) a commit. Sequencer will pause on conflicts. + See the following list and 'GENERAL OPTIONS' for values of `<option>`: -R;; --revert;; Revert the changes introduced by pick <commit>. --mainline=<n>;; --pick-parent=<n>;; Allows you to pick merge commits by specifying the parent number (beginning from 1) to let sequencer replay the changes relative to the specified parent. patch [<options>] <file>:: If file `<file>` is a pure (diff) patch, then apply the patch. If no `--message` option is given, an editor will be invoked to enter a commit message. + If `<file>` is a linkgit:git-format-patch[1]-formatted patch, then the patch will be commited. + See the following list and 'GENERAL OPTIONS' for values of `<option>`: -3;; --3way;; When the patch does not apply cleanly, fall back on 3-way merge, if the patch records the identity of blobs it is supposed to apply to, and we have those blobs available locally. -k;; Pass `-k` flag to `git-mailinfo` (see linkgit:git-mailinfo[1]). -n;; Pass `-n` flag to `git-mailinfo` (see linkgit:git-mailinfo[1]). -u;; Pass `-u` flag to `git-mailinfo` (see linkgit:git-mailinfo[1]). The proposed commit log message taken from the e-mail is re-coded into UTF-8 encoding (configuration variable `i18n.commitencoding` can be used to specify project's preferred encoding if it is not UTF-8). + This was optional in prior versions of git, but now it is the default. You could use `-n` to override this. -*;; Any other dash-prefixed option is passed to linkgit:git-apply[1]. This is especially useful for flags like `--reverse`, `-C<n>`, `-p<n>` or `--whitespace=<action>`. pause:: Pauses the sequencer process to let you manually make changes. For example, you can re-edit the done commit, fix bugs or typos, or you can make further commits on top of HEAD before continuing. + After you have finished your changes and added them to the index, invoke `git-sequencer --continue`. If you only want to edit the last commit message with an editor, run `git commit --amend` (see linkgit:git-commit[1]) before. reset <commit-ish>:: Go back (see linkgit:git-reset[1] `--hard`) to commit `<commit-ish>`. `<commit-ish>` can also be given by a mark, if prefixed with a colon. squash [<options>] <commit>:: Add the changes introduced by `<commit>` to the last commit. + See 'GENERAL OPTIONS' for values of `<option>`. squash [<options>] --up-to <mark>:: Squash all commits up to the given mark into one commit. There must not be any merge commits in between. + See the following list and 'GENERAL OPTIONS' for values of `<option>`: --collect-signoffs;; Collect the Signed-by-off: lines of each commit and add them to the squashed commit message. --include-merges;; Sanity check does not fail if you have merges between HEAD and <mark>. tag <tag>:: Set tag `<tag>` to the current HEAD, see also linkgit:git-tag[1]. If another commit is tagged `<tag>`, it will lose this tag, i.e. the tag will be reset to HEAD. GENERAL OPTIONS --------------- Besides some special options, the instructions `patch`, `merge`, `pick`, `squash` take the following general options: --author=<author>:: Override the author name and e-mail address used in the commit. Use `A U Thor <author@xxxxxxxxxxx>` format. -C <commit-ish>:: --reuse-commit=<commit-ish>:: --reference=<commit-ish>:: Reuse message and authorship data from specified commit. -M <commit-ish> --reuse-message=<commit-ish>:: Reuse message from specified commit. Note, that only the commit message is reused and not the authorship information. -F <file>:: --file=<file>:: Take the commit message from the given file. -m <msg>:: --message=<msg>:: Use the given `<msg>` as the commit message. -s:: --signoff:: Add `Signed-off-by:` line to the commit message (if not yet there), using the committer identity of yourself. RETURN VALUES ------------- git-sequencer returns: * `0`, if git-sequencer successfully completed all the instructions in the TODO file or successfully aborted after `git-sequencer --abort`, * `2`, on user-requested pausing, e.g. when using the `edit` instruction. * `3`, on pauses that are not requested, e.g. when there are conflicts to resolve. * any other value on error, e.g. syntax errors in the TODO file or running git-sequencer on a bare repository. EXAMPLES -------- XXX [Here the usage of all commands should become clear, but it's braindamaged to write this section as long as the file format is in discussion.] SEE ALSO -------- linkgit:git-add[1], linkgit:git-am[1], linkgit:git-cherry-pick[1], linkgit:git-commit[1], linkgit:git-fmt-merge-msg[1], linkgit:git-format-patch[1], linkgit:git-rebase[1], linkgit:git-reset[1], linkgit:git-tag[1] Authors ------- XXX Documentation ------------- Documentation by Stephan Beyer and the git-list <git@xxxxxxxxxxxxxxx>. GIT --- Part of the linkgit:git[1] suite -- Stephan Beyer <s-beyer@xxxxxxx>, PGP 0x6EDDD207FCC5040F -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
