From: Stephan Beyer <s-beyer@gmx.net>
To: git@vger.kernel.org
Cc: Junio C Hamano <gitster@pobox.com>,
Johannes Schindelin <Johannes.Schindelin@gmx.de>,
Jakub Narebski <jnareb@gmail.com>,
Paolo Bonzini <bonzini@gnu.org>,
Pierre Habouzit <madcoder@debian.org>,
Daniel Barkalow <barkalow@iabervon.org>,
Christian Couder <chriscool@tuxfamily.org>
Subject: [RFCv2/FYI] git-sequencer.txt
Date: Thu, 12 Jun 2008 02:22:58 +0200 [thread overview]
Message-ID: <20080612002258.GC7200@leksak.fem-net> (raw)
In-Reply-To: <20080607220101.GM31040@leksak.fem-net>
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@example.com>` 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@vger.kernel.org>.
GIT
---
Part of the linkgit:git[1] suite
--
Stephan Beyer <s-beyer@gmx.net>, PGP 0x6EDDD207FCC5040F
next prev parent reply other threads:[~2008-06-12 0:24 UTC|newest]
Thread overview: 41+ messages / expand[flat|nested] mbox.gz Atom feed top
2008-06-07 22:01 [RFC] git-sequencer.txt Stephan Beyer
2008-06-09 11:45 ` squashing patches (was: Re: [RFC] git-sequencer.txt) Stephan Beyer
2008-06-09 14:04 ` Johannes Schindelin
2008-06-09 15:10 ` squashing patches Paolo Bonzini
2008-06-09 15:43 ` Paolo Bonzini
2008-06-09 16:29 ` Stephan Beyer
2008-06-09 16:37 ` Paolo Bonzini
2008-06-09 20:29 ` [RFC/PATCH] Add git-squash tool and tests Stephan Beyer
2008-06-09 20:34 ` Johannes Schindelin
2008-06-09 20:53 ` Paolo Bonzini
2008-06-09 21:34 ` Johannes Schindelin
2008-06-09 23:42 ` Stephan Beyer
2008-06-10 0:26 ` Johannes Schindelin
2008-06-09 23:46 ` Stephan Beyer
2008-06-09 19:34 ` squashing patches Junio C Hamano
2008-06-09 20:43 ` Stephan Beyer
2008-06-09 20:53 ` Jeff King
2008-06-09 23:57 ` Stephan Beyer
2008-06-10 1:00 ` Jeff King
2008-06-09 21:02 ` Junio C Hamano
2008-06-10 0:38 ` Stephan Beyer
2008-06-09 16:49 ` [RFC] git-sequencer.txt Jakub Narebski
2008-06-10 1:21 ` Stephan Beyer
2008-06-10 4:46 ` Christian Couder
2008-06-10 8:59 ` Stephan Beyer
2008-06-11 4:10 ` Christian Couder
2008-06-11 17:07 ` Daniel Barkalow
2008-06-10 6:17 ` Jakub Narebski
2008-06-12 0:22 ` Stephan Beyer [this message]
2008-06-12 1:31 ` [RFCv2/FYI] git-sequencer.txt Paolo Bonzini
2008-06-12 15:29 ` Stephan Beyer
2008-06-12 15:38 ` [RFC/PATCH] git-commit: Change --reuse-message to --reuse-commit Stephan Beyer
2008-06-12 15:56 ` [RFCv2/FYI] git-sequencer.txt Paolo Bonzini
2008-06-12 5:16 ` Junio C Hamano
2008-06-12 17:07 ` Stephan Beyer
2008-06-13 5:04 ` Paolo Bonzini
2008-06-13 12:16 ` Stephan Beyer
2008-06-13 14:42 ` Paolo Bonzini
2008-06-13 19:24 ` Olivier Marin
2008-06-12 14:10 ` Jakub Narebski
2008-06-12 17:20 ` Stephan Beyer
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20080612002258.GC7200@leksak.fem-net \
--to=s-beyer@gmx.net \
--cc=Johannes.Schindelin@gmx.de \
--cc=barkalow@iabervon.org \
--cc=bonzini@gnu.org \
--cc=chriscool@tuxfamily.org \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=jnareb@gmail.com \
--cc=madcoder@debian.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).