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

Stephan Beyer [off-list ref] writes:

Mentored-by: Christian Couder [off-list ref]
Mentored-by: Daniel Barkalow [off-list ref]

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