git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH 2/5] Add git-sequencer documentation

From
Stephan Beyer <s-beyer@gmx.net>
Date
Jul 30, 2008, 12:14 UTC
Message-ID
<20080730121454.GA8767@leksak.fem-net>
In-Reply-To
<alpine.DEB.1.00.0807261623530.26810@eeepc-johanness>
Hi,
Johannes Schindelin wrote:
Show 6 quoted lines
> > +-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.
> 
> Does it abort, or leave a dirty tree?

It aborts. Perhaps I should make this clear in the docs.

Show 11 quoted lines
> > +--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.
> 
> Whoa, does that mean that
> 
> 	$ git checkout my-private-branch
> 	$ git sequencer --onto=master
> 
> will change _master_?
Exactly.
Show 5 quoted lines
> > +--continue::
> > +	Restart the sequencing process after having resolved a merge conflict.
> 
> What about 'edit'?  Does it restart the sequencing process after editing a 
> file or commit message, too?
Yes. Thanks.
Show 7 quoted lines
> > +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`.
> 
> Speaking of "todo": there was an explicit request to change that to 
> "git-rebase-todo" for rebase -i, so that syntax highlighting could be 
> switched on.

I'd not have a problem with that, though the name "rebase" is not necessarily correct and the syntax files had to be extended nevertheless.

Show 5 quoted lines
> > +-v::
> > +--verbose::
> > +	Be more verbose.
> 
> More?

Hehe, the note that "more" has to be defined more accurately, has been removed. But it is still true. ;)

Show 8 quoted lines
> > +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.
> 
> How about this instead?
> 
> 	Note that sequencing will rewrite the history of the branch.

It will not necessarily rewrite history of a branch. In case of the rebase user command, it does, of course.

Show 6 quoted lines
> 	This will cause problems if you published the branch prior to
> 	rewriting the history, as the former tip is no longer an 
> 	ancestor of the new tip.
> 
> 	In other words, if you rewrite an already published branch, users 
> 	that pull from you _will_ get a bogus merge.
Yes, I can take that.

Well, I wanted only a short note and the user command that really rewrites branches could have a more detailed warning.

> > +'git-sequencer' will usually be called by another git porcelain, like
> 
> s/another git procelain/other git programs/

Ok, I use "other git commands", since this wording seems to be the leading one in other documentation.

Show 6 quoted lines
> > +TODO FILE FORMAT
> > +----------------
> > +
> > +The TODO file contains basically one instruction per line.
> 
> s/basically //

Oh, this is from the times where we included some possible extensions, like a trailing backslash.

Show 7 quoted lines
> > +edit <commit>::
> > +	Pick a commit and pause the sequencer process to let you
> > +	make changes.
> > ++
> > +This is a short form for `pick <commit> and `pause` on separate lines.
> 
> It might make sense to explain 'pick' before 'edit', then.
This is kept alphabetically.

When first writing that, I wondered if this makes sense: a reference-like list should be sorted alphabetically, a tutorial-like list should have some kind of logical structure. I do not really care if we prefer this or that one. So I take your reordering suggestion until somebody complains again :)

Show 6 quoted lines
> > +	--mainline=<n>;;
> > +		Allow you to pick merge commits by specifying the
> > +		parent number (beginning from 1) to let sequencer
> > +		replay the changes relative to the specified parent.
> 
> Why is this called "mainline", and not "parent"?

Because git-cherry-pick/git-revert has "--mainline" and I did not want to rename this.

Show 9 quoted lines
> > [talking about 'squash']
> >
> > +	--collect-signoffs;;
> > +		Collect the Signed-off-by: lines of each commit and
> > +		add them to the squashed commit message.
> > +		(Not yet implemented.)
> 
> I really have to wonder how useful that is.  Or how correct, for that 
> matter.

This is just some kind of squashing Signed-off-by: lines. It was requested by someone (Paolo?) in the RFC git-sequencer.txt thread.

The behavior is planned like this:
Instead of...
	Message of commit 1
	
	Signed-off-by: A
	
	Message of commit 2
	
	Signed-off-by: B
	
	Message of commit 3
	
	Signed-off-by: A
	Signed-off-by: C
...the user gets...
	Message of commit 1
	
	Message of commit 2
	
	Message of commit 3
	
	Signed-off-by: A
	Signed-off-by: B
	Signed-off-by: C
using --collect-signoffs and no commit-message-changing options.
With --message="Foo" this will be:
	Foo
	
	Signed-off-by: A
	Signed-off-by: B
	Signed-off-by: C

For me this sounds like making sense and being useful, but I have not yet digged so deep into the rules of signing off :)

Show 7 quoted lines
> > +	--include-merges;;
> > +		Sanity check does not fail if you have merges
> > +		between HEAD and <mark>.
> 
> It may be a commit, too, right?  And why does it make sense to check that 
> there are no merges?  I mean, it is just as if I did two cherry-picks, the 
> second with -n, and then commit --amend it.  Can make tons of sense...

I think I mean something different. With "merges" I am talking about commits having more than one parent. By this check I want to make sure, that the user really knows what he does when he wants to squash the ones marked with ~ into one commit.

         ~~~~~~~~~~~~~
  ..-A---B---C---D---E---F
            /
  ..-X---Y--
Yet I didn't really care what happens then and perhaps it should be:
 ..--A---S--F
        /
 ..-X-Y-

In the prototype the squashing is done by soft-resetting to the squash base and then commit. As I said, I did not really care if my painted result really happens. In the builtin it will happen :)

Show 6 quoted lines
> > +Here are some examples that shall ease the start with the TODO
> > +file format.
> > +Make sure you have understood the `pick` and perhaps the `patch` command.
> > +Those will not be explained further.
> 
> This sentence is insulting.  Strike it.

The "Make sure ..." sentence? It really is insulting? Do you think it implies the assumption that the user will not grasp patch/pick easily?

Thanks for your reply and your other notes. (The ones I didn't comment are just ACKed.)

Regards,
  Stephan
-- 
Stephan Beyer <s-beyer@gmx.net>, PGP 0x6EDDD207FCC5040F
Previous: Johannes SchindelinNext: Johannes Schindelin
Message 12 of 20 in “git sequencer prototype”
  1. Stephan BeyerJul 26, 2008
  2. 1/5 Add git-sequencer shell prototypeStephan Beyer, Jul 26, 2008
  3. 2/5 Add git-sequencer documentationStephan Beyer, Jul 26, 2008
  4. 3/5 Add git-sequencer test suite (t3350)Stephan Beyer, Jul 26, 2008
  5. 4/5 Migrate git-am to use git-sequencerStephan Beyer, Jul 26, 2008
  6. 5/5 Migrate rebase-i to sequencerStephan Beyer, Jul 26, 2008
  7. Johannes SchindelinJul 26, 2008
  8. Stephan BeyerJul 30, 2008
  9. Jakub NarebskiJul 26, 2008
  10. Sverre RabbelierJul 26, 2008
  11. Johannes SchindelinJul 26, 2008
  12. Stephan BeyerJul 30, 2008
  13. Johannes SchindelinJul 30, 2008
  14. Daniel BarkalowJul 30, 2008
  15. Stephan BeyerJul 31, 2008
  16. Johannes SchindelinJul 26, 2008
  17. Sverre RabbelierJul 26, 2008
  18. Stephan BeyerJul 30, 2008
  19. Johannes SchindelinJul 30, 2008
  20. Stephan BeyerJul 31, 2008

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.