git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
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

  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).