Re: [RFCv2/FYI] git-sequencer.txt

[Jakub Narebski <jnareb@gmail.com>]

Stephan Beyer wrote:
>
> 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

I'm not sure if --edit should be mentioned in line with "processing"
commands: --continue, --skip, --abort and related --status.
 
I'm not sure if it is necessary at all, but if we want to have this
equivalent to "git rebase --interactive" it should be, I think, put
separately.

> Alternatively, you can [...] correct the TODO file with
> 
>     git sequencer --edit

Can you ensure that editor would be invoked with current line
at the current action (isns?)?  Or will you be presenting only
with not performed yet actions?  If not, what would happen if
user modifies actions which had been done already?

In short, this is difficult thing to implement... besides of
course initial edit, with series file seeded by current history
"replay" description.
 
> OPTIONS
> -------
> <file>::
> 	Filename of the TODO file.  If omitted, standard input is used.
> 	See 'TODO FILE FORMAT' below.

Omitted for standard input, --stdin for standard imput, or special
filename of '-' for standard input?
 
> --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.

I'm not sure if repeating rebase design is best idea.  But this
ferature is certainly necessary...
 
> --status::
> 	Show the current status of git-sequencer and what
> 	operations can be done to change that status.

How it would look like?  Current caller, current operation, progress
report (action n/m), status (e.g. CONFLICT or edit, or amend),
suggested actions (--continue, sometimes --skip, --abort)?
 
> --edit::
> 	Invoke editor to edit the undone rest of the TODO file.

Ahh... only the rest of the file...

> -v::
> --verbose::
> 	Be more verbose. [XXX: to be defined more accurately, i.e. print diffstat]

I think it would be nice to have --quiet mode (which perhaps --batch
would imply, or perhaps not), which would make git-sequencer to not
report progress report (i.e. which actions are being done).
 
> git-sequencer will usually be called by another git porcelain, like
> linkgit:git-am[1] or linkgit:git-rebase[1].

Or git-cherry-pick, or git-revert.

-- 
Jakub Narebski
Poland