git@vger.kernel.org list mirror (unofficial, 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>,
	Joerg Sommer <joerg@alea.gnuu.de>,
	Daniel Barkalow <barkalow@iabervon.org>,
	Christian Couder <chriscool@tuxfamily.org>
Subject: [RFC] git-sequencer.txt
Date: Sun, 8 Jun 2008 00:01:01 +0200	[thread overview]
Message-ID: <20080607220101.GM31040@leksak.fem-net> (raw)

Hi,

I inline-attached the documentation (and somehow specification)
for git-sequencer (my GSoC'08 project) for you to comment on.

git-sequencer wants to become the common backend for git-am and 
git-rebase(--interactive) and perhaps some other git commands.
But, if git-sequencer.txt is good enough, you should be able to figure
out yourself, what it can actually be used for :-)

Some background on the project status:
There is already a working (shell) implementation of the following 
specification (90% finished), but we thought that it is useful to 
first give you only a spec without implementation details to comment on.

Note, that there is also a git-am and git-rebase--interactive that use
git-sequencer directly and ... all test cases of the test suite (in "next")
are passed.  So imho a first reality-check is passed, too.

But the second (and perhaps much harder) stage to pass is your 
point of view.
So I hope you will have some good ideas and strong opinions ;-)

Regards,
  Stephan

------------------------------ git-sequencer.txt ------------------------------
git-sequencer(1)
================

NAME
----
git-sequencer - Execute a sequence of git instructions

SYNOPSIS
--------
[verse]
'git-sequencer' [-v | --verbose] <file> [<branch>]
'git-sequencer' --continue | --skip | --abort | --edit


DESCRIPTION
-----------
Executes a sequence of git instructions to HEAD or `<branch>`.
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.  Use `-` to read from standard input.
	See 'TODO FILE FORMAT' below.

<branch>::
	Working branch; defaults to HEAD.

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

--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.
+
After you have finished your changes, invoke `git-sequencer --continue`.
If you only want to edit the commit message with an editor,
run `git-commit --amend` (see linkgit:git-commit[1]) before.
+
Note, that `edit <commit>` is a short form for `pick --edit <commit>`.


file [<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>`.


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>`:

	--reference=<commit-ish>;;
		Take author and commit message of <commit-ish>.
	
	--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 'GENERAL OPTIONS' for values of `<option>`.


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


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
`file`, `merge`, `pick`, `squash` take the following general options:

--edit::
	Allows you to re-edit the done commit. For example, you can change
	the commit message in an editor, or fix even bugs or typos.
	Lets you also manually make further commits on top of the
	current commit before continuing.
+
You will have to invoke `git-sequencer --continue` (or `--edit` or `--abort`),
when finished.

--author=<author>::
	Override the author name and e-mail address used in the commit.
	Use `A U Thor <author@example.com>` format.

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

             reply	other threads:[~2008-06-07 22:02 UTC|newest]

Thread overview: 41+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2008-06-07 22:01 Stephan Beyer [this message]
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 ` [RFCv2/FYI] git-sequencer.txt Stephan Beyer
2008-06-12  1:31   ` 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=20080607220101.GM31040@leksak.fem-net \
    --to=s-beyer@gmx.net \
    --cc=Johannes.Schindelin@gmx.de \
    --cc=barkalow@iabervon.org \
    --cc=chriscool@tuxfamily.org \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=joerg@alea.gnuu.de \
    --subject='Re: [RFC] git-sequencer.txt' \
    /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

git@vger.kernel.org list mirror (unofficial, one of many)

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 git git/ https://public-inbox.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.version-control.git
	nntp://ie5yzdi7fg72h7s4sdcztq5evakq23rdt33mfyfcddc5u3ndnw24ogqd.onion/inbox.comp.version-control.git
	nntp://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/inbox.comp.version-control.git
	nntp://news.gmane.io/gmane.comp.version-control.git
 note: .onion URLs require Tor: https://www.torproject.org/

code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git