Re: [RFC/PATCH 2/4] Add git-sequencer prototype documentation

[Jakub Narebski <jnareb@gmail.com>]

Stephan Beyer <s-beyer@gmx.net> writes:

> Mentored-by: Christian Couder <chriscool@tuxfamily.org>
> Mentored-by: Daniel Barkalow <barkalow@iabervon.org>

Cc mentors?

> +git-sequencer will usually be called by another git porcelain, like
> +linkgit:git-am[1] or linkgit:git-rebase[1].

I hope that it could be also used by git-cherry-pick and git-revert,
so it would be possible to pick more than one commit...

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

Does it run pre-commit hooks, for example checking for merge markers
(but also whitespace errors), and can those checks be disabled?

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

s/.$/ is in the TODO file./

> +--edit::
> +	Invoke editor to edit the undone rest of the TODO file.

Does it mean that editor will be invoked with only _unprocessed_
part of the TODO file?  It looks like it, but it might be not
obvious to some.

> +merge [options] <commit-ish1> <commit-ish2> ... <commit-ishN>::
> +	Merge commits into HEAD.

Nice.

"HEAD" mean last picked up / created commit, isn't it?

> ++
> +A commit can also be given by a mark, if prefixed with a colon.

"You can refer to commit by mark", perhaps?

> +	--standard;;
> +		Generates a commit message like 'Merge ... into HEAD'.
> +		See also linkgit:git-fmt-merge-msg[1].

Is it short for `--standard-message`?

> +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 `options`:
> +
> +	-R;;
> +	--reverse;;
> +		Revert the changes introduced by pick <commit>.
> +
> +	--mainline=<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.
> +		+
> +This option does not work together with `-R`.

Why?  I would have thought that it would work...

> +patch [options] <file>::
[...]
> +	-*;;
> +		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>`.

Do all options make sense?  What about `--index' and `--cached',
or about different no-apply options?

> +ref <ref>::
> +	Set ref `<ref>` to the current HEAD, see also
> +	linkgit:git-update-ref[1].

So this functions like "git reset --soft <ref>", isn't it?

> +squash [options] --from <mark>::
> +	Squash all commits from the given mark into one commit.
> +	There must not be any `merge` instructions between the
> +	`mark` instruction and this `squash --from` instruction.

Can you use <commit> instead of <mark> here?

> +	--include-merges;;
> +		Sanity check does not fail if you have merges
> +		between HEAD and <mark>.

How do you squash merges?  Creating merge with an union of parents,
excluding commits which got squashed?

It means

  ...a---b---c---d         ...[abcd]
            /        ==>        /
      ...x-/               ..x-/

but

  ...a---b---c---d          ...[abcd]
      \     /        ==>
       \-x-/ 

> +RETURN VALUES
> +-------------
> +* any other value on error, e.g.
> +  running git-sequencer on a bare repository.

Don't you enumerate those return values?

-- 
Jakub Narebski
Poland
ShadeHawk on #git