[StGIT RFC] Changing patch@branch syntax

[StGIT RFC] Changing patch@branch syntax

[Yann Dirson]

The patch@branch syntax is annoying, at least for bash-completion
purposes: we don't want to provide all possible completions accross
all branches, yet we'd like to get completion for foreign patches.

Another place where I feel it is bad is when using the full
"patch@branch//top" syntax: the MSB is in the middle, and the LSB is
on the right.

Both issues would be solved by switching to a MSB ordering, with a way
to distinguish branchnames when given.  Something similar to pathnames
would fit well - eg. [/branchname/]patchname[//top].  However, I'm not
sure using slashes would be a good choice, precisely because of the
similarity with real pathnames.  But we don't have so many separator
chars that are not special in one way or another, and would require
quoting them to avoid more user confusion.

What do you think ?
-- 
Yann.

Re: [StGIT RFC] Changing patch@branch syntax

[Karl Hasselström]

On 2007-05-16 00:03:10 +0200, Yann Dirson wrote:

> The patch@branch syntax is annoying, at least for bash-completion
> purposes: we don't want to provide all possible completions accross
> all branches, yet we'd like to get completion for foreign patches.

Yes, that's annoying.

> Another place where I feel it is bad is when using the full
> "patch@branch//top" syntax: the MSB is in the middle, and the LSB is
> on the right.

I agree. (Similarly, YYYYMMDD is the one true date format!)

> Both issues would be solved by switching to a MSB ordering, with a
> way to distinguish branchnames when given. Something similar to
> pathnames would fit well - eg. [/branchname/]patchname[//top].
> However, I'm not sure using slashes would be a good choice,
> precisely because of the similarity with real pathnames. But we
> don't have so many separator chars that are not special in one way
> or another, and would require quoting them to avoid more user
> confusion.

Branch names can contain slashes, and in the future patch names might
as well, so we'd need another separator. _Except_ for the fact that if
foo/bar is a branch, foo/bar/baz can't also be a branch, so using a
slash as separator is actually unambiguous.

If we similarly make it illegal for patches a/b and a/b/c to exist
simultaneously (whenever we get around to implementing slashy patch
names), we could use a single slash for patchname/{top,bottom} too.

The only remaining difficulty is to decide whether a/b/c is patch b/c
on branch a, or patch a/b/c on the current branch. We can't forbid
patch names and branch names to collide, since git can create new
branch names behind stgit's back. So I guess we'd need some way to
indicate whether branch name is included. The leading slash in your
suggestion seems as good a way as any.

However, I'm not going to recommend using only slashes. I believe life
will be much simpler if we simply use two different separators, like
this:

  branch:patch@top

Then all these subsets will be trivially parseable:

  branch:patch

  patch

  patch@top

And even this one, if we feel crazy some day:

  /path/to/other/repository#branch:patch@top

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle

Re: [StGIT RFC] Changing patch@branch syntax

[Catalin Marinas]

On 15/05/07, Yann Dirson <ydirson@altern.org> wrote:
> The patch@branch syntax is annoying, at least for bash-completion
> purposes: we don't want to provide all possible completions accross
> all branches, yet we'd like to get completion for foreign patches.
>
> Another place where I feel it is bad is when using the full
> "patch@branch//top" syntax: the MSB is in the middle, and the LSB is
> on the right.

I agree that the current syntax is bad.

> Both issues would be solved by switching to a MSB ordering, with a way
> to distinguish branchnames when given.  Something similar to pathnames
> would fit well - eg. [/branchname/]patchname[//top].  However, I'm not
> sure using slashes would be a good choice, precisely because of the
> similarity with real pathnames.  But we don't have so many separator
> chars that are not special in one way or another, and would require
> quoting them to avoid more user confusion.

We had a discussion some time ago about using slashes for the //top or
//bottom syntax and we ended up using two slashes. We could do the
same to delimitate the branch from the patch - branch//patch//top. The
branch or patch can have (single) slashes in their name.

We couldn't use ":" at that time as it was used for the 'diff -r x:y'
command. I later switched to the git ".." format (when git eventually
defined it). As Karl said, branch:patch@top is another way, unless we
later decide to add another level, the repository, and would like to
have a uniform syntax (maybe always use ":" instead of "//"). We could
run commands like:

  stg pick ../../path/to/linux-repo//branch//patch

I don't think using "#" is feasible as bash ignores everything after
it unless you use quotes or escape.

Another nice thing to have is a way to get older versions of a patch
via patchlogs. This should probably follow the current git notation,
i.e. patch^^^ or patch~N.

-- 
Catalin

Re: [StGIT RFC] Changing patch@branch syntax

[Yann Dirson]

On Tue, May 22, 2007 at 01:27:08PM +0100, Catalin Marinas wrote:
> We had a discussion some time ago about using slashes for the //top or
> //bottom syntax and we ended up using two slashes. We could do the
> same to delimitate the branch from the patch - branch//patch//top. The
> branch or patch can have (single) slashes in their name.
> 
> We couldn't use ":" at that time as it was used for the 'diff -r x:y'
> command. I later switched to the git ".." format (when git eventually
> defined it). As Karl said, branch:patch@top is another way, unless we
> later decide to add another level, the repository, and would like to
> have a uniform syntax (maybe always use ":" instead of "//"). We could
> run commands like:
> 
>  stg pick ../../path/to/linux-repo//branch//patch

Indeed I would possibly already have used this if it had been
available (working with 2 working copies for 2 cvs branches of a
single project, using stg-cvs in each).


> I don't think using "#" is feasible as bash ignores everything after
> it unless you use quotes or escape.

No, bash only considers # as a comment leader if there is space before
it, which would not be the case here (and is why the
http://repo#branch in cogito worked without problems).  Not sure about
other shells, though.

I'm not very comfortable with // either, since having it special makes
it harder for script writers (need to canonicalize dirnames to ensure
a double slash is not inserted by error).  Whereas it's not a big
problem to solve when the script writer is aware of the problem, it's
not something everyone would think about, and it may even break
existing scripts.


Following the "stg pick" example above, would we also want to allow
picking from a remote repo ?  Then the URL fragment notation could be
suited, and we could have something like:

	http://full/path/to/repo#my/branch:my/patch//top

That is, a formal syntax of:

	[[[repo#]branch:]patch][//modifier]

Going further, since specifying a repo without a branch probably has
no meaning (unless we want to default to the HEAD branch), we could
simplify to the following:

	[[[repo#]branch#]patch][//modifier]

I don't think we really want to allow "repo#patch", meaning that patch
on the current branch, as this gets easily confused by branch switching.


> Another nice thing to have is a way to get older versions of a patch
> via patchlogs. This should probably follow the current git notation,
> i.e. patch^^^ or patch~N.

Yes, that's something I've thought about several times, without coming
with a satisfying solution either: using the git notation to refer to
something different is not a good idea (we already have a "push"
command with a completely different meaning, let's keep these beasts
out if possible ;).  There is already another syntax used by git for
reflogs (ref@{N}), which would have the same problem.

We should also keep in mind that someday we'll surely have merge
entries in patchlogs (one of the things near the top of my todo list),
so the same facility available in git for commit parents as ref^N will
be useful as well.

Another thing is, it would be great if the syntax we elect for this
would be "reserved" by git-core, so git-core does not start to use it
one day and cause a conflict.  Maybe it could be "reserved" so other
porcelains can as well use it (yes, there is the problem of how those
other porcelains interact with stgit then - or rather, how will we
help the user not to get confused) ?

Best regards,
-- 
Yann.

Re: [StGIT RFC] Changing patch@branch syntax

[Yann Dirson]

Working in the implementation of hydras/pools, as well as discussing
of their future, led me to the following thoughts, quite related to
how we should select a new syntax for patches.

First, as a foreword, a bit if refactoring: I think we should use some
sort of Stackable (maybe pick a better name) class as a parent for
Patch and PatchSet.  Instances of a Stackable would be candidates to
be members of a PatchSet.  That means we can have stacks within a
stack, as well as stacks members of a pool.  But we also need a syntax
to name stacks-(in-a-stack)*, and patches within them.

Second, but not least, we currently have an ambiguity in syntax: "foo"
can mean "patch foo in current branch" or "branch foo", depending on
the context, and that is *really* bad.  What's more, my former
proposal (quoted below) does not improve this issue.  And my previous
proposal, which suggested using a prefix like "/stack/patch" for a
fully qualified patch and "patch" for a relative one does not solve
that problem either, and brings the additional annoyance of
introducing a syntax that is incompatible with git-core.

So here is a new proposal, which I believe would address all current
issues, at the expense of changing stgit syntax.  The idea is to use a
single separator for all levels of Stackable objects, with an optional
"patch id" (eg. //top) at the end when meaningful.  Only names would
be possible to omit, separators would be mandatory to specify the
nesting level.  That gives a syntax of:

	[patchset]([:stackable]+(//id)?)*

Examples:

	<stack>			the named branch (git-compatible)
	<stack>:<patch>		named patch in named stack
	:<patch>		named patch in current patchset (currently just "<patch>")
	<stack>:		current (top) patch in named patchset
	<pool>:<stack>:<patch>	fully-qualified patch in a named hydra
	::			top patch of the current stack of an hydra
	:<stack>://bottom.old	previous bottom of the top patch in the named stack of current pool


How does that feel ?


On Tue, May 22, 2007 at 11:00:20PM +0200, Yann Dirson wrote:
> Following the "stg pick" example above, would we also want to allow
> picking from a remote repo ?  Then the URL fragment notation could be
> suited, and we could have something like:
> 
> 	http://full/path/to/repo#my/branch:my/patch//top
> 
> That is, a formal syntax of:
> 
> 	[[[repo#]branch:]patch][//modifier]
> 
> Going further, since specifying a repo without a branch probably has
> no meaning (unless we want to default to the HEAD branch), we could
> simplify to the following:
> 
> 	[[[repo#]branch#]patch][//modifier]
> 
> I don't think we really want to allow "repo#patch", meaning that patch
> on the current branch, as this gets easily confused by branch switching.

Re: [StGIT RFC] Changing patch@branch syntax

[Catalin Marinas]

On 22/06/07, Yann Dirson <ydirson@altern.org> wrote:
> First, as a foreword, a bit if refactoring: I think we should use some
> sort of Stackable (maybe pick a better name) class as a parent for
> Patch and PatchSet.  Instances of a Stackable would be candidates to
> be members of a PatchSet.  That means we can have stacks within a
> stack, as well as stacks members of a pool.  But we also need a syntax
> to name stacks-(in-a-stack)*, and patches within them.

I'm OK with refactoring the code this way (the current code is based
on the initial prototype but it evolved a lot since then).

> So here is a new proposal, which I believe would address all current
> issues, at the expense of changing stgit syntax.  The idea is to use a
> single separator for all levels of Stackable objects, with an optional
> "patch id" (eg. //top) at the end when meaningful.  Only names would
> be possible to omit, separators would be mandatory to specify the
> nesting level.  That gives a syntax of:
>
>         [patchset]([:stackable]+(//id)?)*

I don't think I can write a regexp for it but I don't like the
mandatory ":" before the patch name (or stackable object). The main
reason is that one usually works on a branch with patch names, there
might be scripts+xargs involved and forcing the use of ":" would make
it more complicated.

I also don't think we need to make this distinction in the names as
different commands or options take different type of arguments:

stg show <patch>
stg series --branch <stack>

I'll try to express this with BNF (though I'm not an expert in this notation):

<name> ::= "" | [^\w.-]+
<attr> ::= top | top.old | bottom | bottom.old | log | ...
<nameattr> ::= <name> | <name>//<attr>

<stackable> ::= <nameattr> | <stackable>:<stackable>

If empty name (""), the current object for the level is used.

The above <stackable> is more generic. A patchset might have other
attributes or none at all (could have a "old" attribute if we decide
to keep older versions of a stack for example).

In terms of our patches, stacks etc.:

<pool> ::= <name>
<stack> ::= <name> | <pool>:<name>
<patch> ::= <nameattr> | <stack>:<nameattr>

I would introduce a <repo> in front of all the above (for which we
don't have any support) but this is somehow at a similar level to
<pool> in case we don't use a hydra. Or the <pool> can also be a
repository?

> Examples:
>
>         <stack>                 the named branch (git-compatible)

<patch> - named patch in the current patchset

>         <stack>:<patch>         named patch in named stack

OK

>         :<patch>                named patch in current patchset (currently just "<patch>")

OK, the same as <patch>

>         <stack>:                current (top) patch in named patchset

OK (maybe use should use "current" rather than "top" in the
description as it applies better to other stackable objects)

>         <pool>:<stack>:<patch>  fully-qualified patch in a named hydra

OK

>         ::                      top patch of the current stack of an hydra

OK (current patch of the current stack)

>         :<stack>://bottom.old   previous bottom of the top patch in the named stack of current pool

OK

-- 
Catalin

Re: [StGIT RFC] Changing patch@branch syntax

[Yann Dirson]

On Fri, Jun 22, 2007 at 04:59:05PM +0100, Catalin Marinas wrote:
> >So here is a new proposal, which I believe would address all current
> >issues, at the expense of changing stgit syntax.  The idea is to use a
> >single separator for all levels of Stackable objects, with an optional
> >"patch id" (eg. //top) at the end when meaningful.  Only names would
> >be possible to omit, separators would be mandatory to specify the
> >nesting level.  That gives a syntax of:
> >
> >        [patchset]([:stackable]+(//id)?)*
> 
> I don't think I can write a regexp for it but I don't like the
> mandatory ":" before the patch name (or stackable object). The main
> reason is that one usually works on a branch with patch names, there
> might be scripts+xargs involved and forcing the use of ":" would make
> it more complicated.

That's probably not much of a problem: patch lists could be generated
for script use with a flag similar to "series --showbranch".


> I also don't think we need to make this distinction in the names as
> different commands or options take different type of arguments:
> 
> stg show <patch>
> stg series --branch <stack>

Currently, "stg show HEAD" or any other git ref does work, except when
there are name clashes.

And since we're going to have all of patches, stacks, and pools in the
same "stackable" family, we're going to use them interchangeably in
more and more places.  But there are also places where we can use at
will stack names and generic git heads (eg. "stg branch X").

I'd rather having a single name-resolution mechanism, instead of one
for patches and one for branches.


> I'll try to express this with BNF (though I'm not an expert in this 
> notation):
> 
> <name> ::= "" | [^\w.-]+
> <attr> ::= top | top.old | bottom | bottom.old | log | ...
> <nameattr> ::= <name> | <name>//<attr>
> 
> <stackable> ::= <nameattr> | <stackable>:<stackable>
> 
> If empty name (""), the current object for the level is used.
> 
> The above <stackable> is more generic. A patchset might have other
> attributes or none at all (could have a "old" attribute if we decide
> to keep older versions of a stack for example).

Right, good idea.


> I would introduce a <repo> in front of all the above (for which we
> don't have any support)

Yes - URLs could do the work, with a '#' to use the stackable as URL
fragment.


> but this is somehow at a similar level to <pool> in case we don't
> use a hydra. Or the <pool> can also be a repository?

I think they are different enough: a pool/hydra typically has several
members applied, whereas a repo has only a current branch.



Now for technical details.  I have a prototype hydra mechanism that
demonstrates that we can create such a beast without having everything
breaking all around.  However, it does not use the model described in
this thread, but rather links to stacks which exist independantly - I
want to keep that as a possibility, by using some symlink-like
mechanism, but the current prototype will not live, although I may
experiment a bit more with it.  BTW, we should probably name the final
beast "pool" and not "hydra", so users have a better idea of how to
use it :)

However, the various refactorings and fixes I have done should be
quite ready for inclusion (modulo dispatching recent fixes down to the
relevant patch).  Here I need to know your plans for 0.13: if the
refactoring would go in, I just have to polish things as they are; if
you prefer to keep this for 0.14, I'll sink the bugfixes down my stack
so they can be in 0.13 at least.

Did you have time to look at the various refactorings at
http://repo.or.cz/w/stgit/ydirson.git ?

Best regards,
-- 
Yann

Re: [StGIT RFC] Changing patch@branch syntax

[Catalin Marinas]

On 22/06/07, Yann Dirson <ydirson@altern.org> wrote:
> On Fri, Jun 22, 2007 at 04:59:05PM +0100, Catalin Marinas wrote:
> > I also don't think we need to make this distinction in the names as
> > different commands or options take different type of arguments:
> >
> > stg show <patch>
> > stg series --branch <stack>
>
> Currently, "stg show HEAD" or any other git ref does work, except when
> there are name clashes.

But the argument to 'show' here is either a patch or a git ref (not a
stack or a pool). It first tries to find a patch and fall back to a
git ref. You don't specify a stack to 'show'. 'git show' is also able
to take a commit or a tag object without clearly specifying the
difference.

What might be easier with a complete spec is bash completion. I find
this mandatory precise description similar to the Hungarian notation.
Since most of the time I work with push/pop commands, I don't like
always putting a ":" for every patch (BTW, what about patch ranges, I
don't think they can go across multiple stacks).

> And since we're going to have all of patches, stacks, and pools in the
> same "stackable" family, we're going to use them interchangeably in
> more and more places.  But there are also places where we can use at
> will stack names and generic git heads (eg. "stg branch X").

Currently, stack names and git branches are the same. Would this
change with hydra? I use StGIT to maintain my branches on
http://www.linux-arm.org/git?p=linux-2.6.git;a=heads and I find the
stack name == git branch simplification pretty useful.

What commands/options would we have where we need to distinguish
between stack and patch names?

> I'd rather having a single name-resolution mechanism, instead of one
> for patches and one for branches.

I don't see why we couldn't have a single name resolution but without
the mandatory ":". An example (but in reverse order) is internet
names. I only type "intranet" rather than "intranet." in a browser. To
fully qualify, I type "intranet.arm.com".

> > I would introduce a <repo> in front of all the above (for which we
> > don't have any support)
>
> Yes - URLs could do the work, with a '#' to use the stackable as URL
> fragment.

OK, you mentioned this in the past.

> Now for technical details.  I have a prototype hydra mechanism that
> demonstrates that we can create such a beast without having everything
> breaking all around.  However, it does not use the model described in
> this thread, but rather links to stacks which exist independantly - I
> want to keep that as a possibility, by using some symlink-like
> mechanism, but the current prototype will not live, although I may
> experiment a bit more with it.  BTW, we should probably name the final
> beast "pool" and not "hydra", so users have a better idea of how to
> use it :)

Yes, "pool" sounds better (though I didn't get the full idea of how
things work).

> However, the various refactorings and fixes I have done should be
> quite ready for inclusion (modulo dispatching recent fixes down to the
> relevant patch).  Here I need to know your plans for 0.13: if the
> refactoring would go in, I just have to polish things as they are; if
> you prefer to keep this for 0.14, I'll sink the bugfixes down my stack
> so they can be in 0.13 at least.

I plan to do a 0.13 release pretty soon. I want to clear some of the
logged bugs and release it as it seems to be pretty stable. It's
better to keep this refactoring for 0.14.

If it is easier for you, you could create a branch (for-upstream etc.)
and just send me an email to merge it.

> Did you have time to look at the various refactorings at
> http://repo.or.cz/w/stgit/ydirson.git ?

I had a quick look (not much though, moving house and a lot of FYI).
They look OK, but just a few comments:

- concreteCommand, I would write classes with capital first letter
(unwritten convention in StGIT)

- why the Repository class definition in stgit/__init__.py? Can it not
be in a different file? Also, shourt stgit/git.py be aware of the
repository?

Regards.

-- 
Catalin

Re: [StGIT RFC] Changing patch@branch syntax

[Yann Dirson]

On Fri, Jun 22, 2007 at 11:29:14PM +0100, Catalin Marinas wrote:
> On 22/06/07, Yann Dirson <ydirson@altern.org> wrote:
> >On Fri, Jun 22, 2007 at 04:59:05PM +0100, Catalin Marinas wrote:
> >> I also don't think we need to make this distinction in the names as
> >> different commands or options take different type of arguments:
> >>
> >> stg show <patch>
> >> stg series --branch <stack>
> >
> >Currently, "stg show HEAD" or any other git ref does work, except when
> >there are name clashes.
> 
> But the argument to 'show' here is either a patch or a git ref (not a
> stack or a pool). It first tries to find a patch and fall back to a
> git ref. You don't specify a stack to 'show'.

Well, currently "stg show <stack>" will just take <stack> as a git
ref, and will show the top commit, which may well be the base commit
of the stack - not very exciting, I agree.


> What might be easier with a complete spec is bash completion. I find
> this mandatory precise description similar to the Hungarian notation.
> Since most of the time I work with push/pop commands, I don't like
> always putting a ":" for every patch

Right, push/pop should only get the local name in the current
patchset, no ":" whatsoever in there.  It is not the same for "show",
since we often want to look at patches in other stacks.


> (BTW, what about patch ranges, I don't think they can go across
> multiple stacks).

Right - we probably only want ranges in the rightmost component of a
patchspec.


> >And since we're going to have all of patches, stacks, and pools in the
> >same "stackable" family, we're going to use them interchangeably in
> >more and more places.  But there are also places where we can use at
> >will stack names and generic git heads (eg. "stg branch X").
> 
> Currently, stack names and git branches are the same. Would this
> change with hydra? I use StGIT to maintain my branches on
> http://www.linux-arm.org/git?p=linux-2.6.git;a=heads and I find the
> stack name == git branch simplification pretty useful.
> 
> What commands/options would we have where we need to distinguish
> between stack and patch names?

I have often wondered if it would be useful to have a given
patch@stack as a base for another stack, or maybe as one of the
"heads" of an hydra.  Still not sure it would make any sense, however
- especially, proper use of hydras would possibly suppress the need
for the former.


> >I'd rather having a single name-resolution mechanism, instead of one
> >for patches and one for branches.
> 
> I don't see why we couldn't have a single name resolution but without
> the mandatory ":". An example (but in reverse order) is internet
> names. I only type "intranet" rather than "intranet." in a browser. To
> fully qualify, I type "intranet.arm.com".

There is a difference, in that in name resolution there is a
well-define algorithm to resolve this, and in that "intranet" alone is
not a valid fully-qualified name.  In current StGIT, in cases where
"name" matches both a local patch a git ref... well, we can still ask
for refs/heads/name as fully-qualified name - looks like I had
forgotten that one ;)


Let's try to find a proper solution.

We have on one hand a number of commands (in the patch/stack sets)
that act solely within the patchset, and thus have no need for
referencing stackables outside the current patchset:

	new, push, pop, goto, float, sink, clean, uncommit, export,
	import, mail, refresh 

Similar commands, but which no technical issue restrain from acting on
stackables in other patchsets:

	delete, hide, unhide, patches, series, files, log, rename, show

Commands that solely refer to patchsets, not stackables:

	applied, unapplied, top, branch, rebase

Commands that need to refer to patches in other patchsets:

	pick

Commands that don't care:

	assimilate, commit, init, pull, fold


I consider we have a couple of special cases:

	clean currently does not care, but see task #5235
	rebase currently only needs patchets, do we need to extend that to patches ?
	mail currently does not accept --branch or patch@stack but probably could
	new creates a patch in the current stack, we may want to unify
		this with "branch -c" in some way (maybe "stg
		(patch|stack|pool) new" ?)
	show is special in that when its arg is not a ref to a patch,
		it falls back to git-show.  We may want to change
		that, to be an stgit-only command.
	sync uses non-standard way to refer to the other stack - do we
		really need to sync several patches in one command ?

	clone is also special, in that it is currently the only one to
		have a use for the repo - it could surely be extended
		to accept a stackable (eg. "stg clone http://this/repo#pool2:stk1")

To summarize, appart from "show" which does not really need to know
about branches, no current command would have any ambiguity.

A couple of commands in the 1st category will needto be enhanced to be
more useful with pools of stacks (to specify which stack of the pool
to act on), but that does not change the problem, they do not act on
non-stackable git-core branches.


> If it is easier for you, you could create a branch (for-upstream etc.)
> and just send me an email to merge it.

Right.  With a bit more work on hydra/pool, I could even tell you to
pull from an pool member ;)


> - concreteCommand, I would write classes with capital first letter
> (unwritten convention in StGIT)

OK


> - why the Repository class definition in stgit/__init__.py? Can it not
> be in a different file?

This is part of the things to clean up.  By putting it here I was sure
the class was going to available as stgit.Repository.  I'm not fluent
in python yet, I'll have to dig for a better way - that one surely
does not scale at all.


> Also, shourt stgit/git.py be aware of the repository?

I'd rather think that we should have git.Repository (and further
structurate git.py with more objects, like git.Branch), with
stgit-specific stuff in the stgit.Repository subclass.

Best regards,
-- 
Yann.

Re: [StGIT RFC] Changing patch@branch syntax

[Catalin Marinas]

On 24/06/07, Yann Dirson <ydirson@altern.org> wrote:
> Well, currently "stg show <stack>" will just take <stack> as a git
> ref, and will show the top commit, which may well be the base commit
> of the stack - not very exciting, I agree.

Indeed. The 'show' command was meant for patches but I added the
support to fall back to git commits.

> > What might be easier with a complete spec is bash completion. I find
> > this mandatory precise description similar to the Hungarian notation.
> > Since most of the time I work with push/pop commands, I don't like
> > always putting a ":" for every patch
>
> Right, push/pop should only get the local name in the current
> patchset, no ":" whatsoever in there.  It is not the same for "show",
> since we often want to look at patches in other stacks.

Yes, but most of the time I look at patches on the current branch.

> I have often wondered if it would be useful to have a given
> patch@stack as a base for another stack, or maybe as one of the
> "heads" of an hydra.  Still not sure it would make any sense, however
> - especially, proper use of hydras would possibly suppress the need
> for the former.

There are situations when I want a separate branch but it relies on
patches in other branches. I currently duplicate the patches and use
the 'sync' command to keep them up to date (though this command would
be more useful with support for git-rerere to avoid fixing the same
conflict several times).

Can a patch series be part of multiple pools? This would be useful to
my workflow.

> > >I'd rather having a single name-resolution mechanism, instead of one
> > >for patches and one for branches.
> >
> > I don't see why we couldn't have a single name resolution but without
> > the mandatory ":". An example (but in reverse order) is internet
> > names. I only type "intranet" rather than "intranet." in a browser. To
> > fully qualify, I type "intranet.arm.com".
>
> There is a difference, in that in name resolution there is a
> well-define algorithm to resolve this, and in that "intranet" alone is
> not a valid fully-qualified name.

No, it's not fully qualified but it gets the .arm.com by default. If
it fails, the browser will complain.

> In current StGIT, in cases where
> "name" matches both a local patch a git ref... well, we can still ask
> for refs/heads/name as fully-qualified name - looks like I had
> forgotten that one ;)

StGIT could default to patches and fall back to git commits if no ":"
are found in the name.

> Let's try to find a proper solution.
>
> We have on one hand a number of commands (in the patch/stack sets)
> that act solely within the patchset, and thus have no need for
> referencing stackables outside the current patchset:
>
>         new, push, pop, goto, float, sink, clean, uncommit, export,
>         import, mail, refresh
>
> Similar commands, but which no technical issue restrain from acting on
> stackables in other patchsets:
>
>         delete, hide, unhide, patches, series, files, log, rename, show
>
> Commands that solely refer to patchsets, not stackables:
>
>         applied, unapplied, top, branch, rebase

Those that can refer to other patchsets have the '--branch' argument,
otherwise they just use the current series.

> Commands that need to refer to patches in other patchsets:
>
>         pick
>
> Commands that don't care:
>
>         assimilate, commit, init, pull, fold
>
>
> I consider we have a couple of special cases:
>
>         clean currently does not care, but see task #5235
>         rebase currently only needs patchets, do we need to extend that to patches ?

'rebase' could only work on the current patchset because of the
possibility of getting conflicts during push (unless you implement the
branch switching as well).

>         mail currently does not accept --branch or patch@stack but probably could

Yes.

>         new creates a patch in the current stack, we may want to unify
>                 this with "branch -c" in some way (maybe "stg
>                 (patch|stack|pool) new" ?)

This might be a possibility once we refactor the command line.

>         show is special in that when its arg is not a ref to a patch,
>                 it falls back to git-show.  We may want to change
>                 that, to be an stgit-only command.

We need the commit id generation for the 'pick' command and 'show'
would use the same code. I don't think we should restrict it.

>         sync uses non-standard way to refer to the other stack - do we
>                 really need to sync several patches in one command ?

I have stacks with more than 10 common patches and it is useful to
update them with only one command (I do this many times only as a
simple check).

>         clone is also special, in that it is currently the only one to
>                 have a use for the repo - it could surely be extended
>                 to accept a stackable (eg. "stg clone http://this/repo#pool2:stk1")

Yes, it would be nice.

> To summarize, appart from "show" which does not really need to know
> about branches, no current command would have any ambiguity.

If we don't want ambiguities in the UI, we could restrict 'show' only
to the StGIT patches (though I personally don't mind the fall-back to
GIT objects).

> > Also, shourt stgit/git.py be aware of the repository?
>
> I'd rather think that we should have git.Repository (and further
> structurate git.py with more objects, like git.Branch), with
> stgit-specific stuff in the stgit.Repository subclass.

Sounds good.

Thanks.

-- 
Catalin

Re: [StGIT RFC] Changing patch@branch syntax

[Yann Dirson]

On Mon, Jun 25, 2007 at 11:22:15PM +0100, Catalin Marinas wrote:
> >I have often wondered if it would be useful to have a given
> >patch@stack as a base for another stack, or maybe as one of the
> >"heads" of an hydra.  Still not sure it would make any sense, however
> >- especially, proper use of hydras would possibly suppress the need
> >for the former.
> 
> There are situations when I want a separate branch but it relies on
> patches in other branches. I currently duplicate the patches and use
> the 'sync' command to keep them up to date (though this command would
> be more useful with support for git-rerere to avoid fixing the same
> conflict several times).
> 
> Can a patch series be part of multiple pools? This would be useful to
> my workflow.

In the current prototype, yes, since the current "hydra" object only
binds existing stacks.  In the design we've discussed, not directly -
let's find a solution.

My idea of what we've discussed most recently is that stackables will
be *contained* in patchsets.  Ie. a pool will be able to contain both
patches-as-we-know-them, and stacks, but those stacks won't be git
heads, only refs in a namespace still to be decided upon - something
similar to how we currently store patch refs.

To allow sharing a stack between several pools, I can see 2 options.
The easiest to implement (but not necessarily the easiest to live
with) is to clone and sync the stack.

Another one is to add another Stackable subclass (eg. StackableLink),
that would figure some sort of symbolic link to the reference
Stackable.  It would provide in the current patchset a local name for
the linked Stackable, but may need to be more than a simple alias: a
pool is, at least for now, an octopus, and thus only supports
conflict-less members; thus, if the linked Stackable changes to be
incompatible with the link siblings, the patchset containing the
conflict would instantly become invalid.  Either we add support for
this "invalidated" status, or we find a better way.  One possibility I
thought of, is that the link will point a specific version of its
referenced stackable (a point always reachable from new versions of
the referenced stackable through its patch/ref/stack/whatever-log),
and the user will need to explicitely stg-pull to get the new version,
with the option to "pull --undo" if he does not like it.

All these options leave room for innovative workflows :)


> >In current StGIT, in cases where
> >"name" matches both a local patch a git ref... well, we can still ask
> >for refs/heads/name as fully-qualified name - looks like I had
> >forgotten that one ;)
> 
> StGIT could default to patches and fall back to git commits if no ":"
> are found in the name.

I'd rather leave this fallback to the minimum (esp. if only "show" and
"pick" can make sense out of it).


> >I consider we have a couple of special cases:
> >
> >        clean currently does not care, but see task #5235
> >        rebase currently only needs patchets, do we need to extend that to 
> >        patches ?
> 
> 'rebase' could only work on the current patchset because of the
> possibility of getting conflicts during push (unless you implement the
> branch switching as well).

That's not what I was thinking about.  I was mentionning the
possibility to rebase to a given patch, so "pull" will follow later
versions of that patch.  Not sure it is useful, though, and it can
probably already be done by rebasing to refs/patches/<branch>/<patch>
(although that accesses implementation details, that rebasing to
<branch>:<patch> would not need to).


> >        new creates a patch in the current stack, we may want to unify
> >                this with "branch -c" in some way (maybe "stg
> >                (patch|stack|pool) new" ?)
> 
> This might be a possibility once we refactor the command line.

Right - that was subliminally suggesting to refactor the command-line
before 1.0, in fact ;)


> >> Also, shourt stgit/git.py be aware of the repository?
> >
> >I'd rather think that we should have git.Repository (and further
> >structurate git.py with more objects, like git.Branch), with
> >stgit-specific stuff in the stgit.Repository subclass.
> 
> Sounds good.

Cool.

Best regards,
-- 
Yann

Re: [StGIT RFC] Changing patch@branch syntaxtackable> ::= <nameattr> | <stackable>:<stackable>

[Yann Dirson]

My thoughts about stg-show suggested me we can extend on the latest
proposed syntax, by allowing comma-separated sequences of patch
ranges.  Such ranges would not be limitted to patches either, they
would be meaningful within any patchset (or maybe within ordered
patchsets only, should we feel this restriction necessary).  Eg:

	stg show <pool>:<stack>:foo,bar..buz

Patch attributes OTOH probably don't play well with ranges - which I
take as a symptom that we should be careful about them.

We may also want to generalize the patch//attribute mechanism a bit
more, eg. so "base" is not seen as a fake patch, but rather an
attribute of the patchset.  That is, something like
"<pool>:<stack>//base" should be a valid id.

Let's try to get a full formal syntax, based on the one you formerly
proposed.

    <name> ::= [^\w.-]+
    <attr> ::= 'top' | 'top.old' | 'bottom' | 'bottom.old' | 'log' | ...
    <patchname>|<stackname>|<poolname>|<hydraname> ::= <name>
    <patchsetname> ::= <stackname> | <poolname> | <hydraname>

    <patchset> ::= <patchsetname> ? | <patchset> ':' <patchsetname> ?
    <patch> := <patchset> ':' <patchname>

    <commitid> ::= ( <patch> | <patchset> ) ? '//' <attr>

    <simplerange0> ::= <name> | <name> '..' <name>? | '..' <name>
    <simplerange> ::= <simplerange> | <simplerange0> ',' <simplerange>

    <range> := <patchset> ':' <simplerange>


On Wed, Jun 27, 2007 at 12:31:43AM +0200, Yann Dirson wrote:
> On Mon, Jun 25, 2007 at 11:22:15PM +0100, Catalin Marinas wrote:
> > Can a patch series be part of multiple pools? This would be useful to
> > my workflow.
>
> In the current prototype, yes, since the current "hydra" object only
> binds existing stacks.  In the design we've discussed, not directly -
> let's find a solution.
>
> My idea of what we've discussed most recently is that stackables will
> be *contained* in patchsets.  Ie. a pool will be able to contain both
> patches-as-we-know-them, and stacks, but those stacks won't be git
> heads, only refs in a namespace still to be decided upon - something
> similar to how we currently store patch refs.
>
> To allow sharing a stack between several pools, I can see 2 options.
> The easiest to implement (but not necessarily the easiest to live
> with) is to clone and sync the stack.

Given the complexity of the approaches I proposed, we may want to keep
an "hydra" type besides "pools".  After all, we may implement as many
PatchSet subclasses we can think of :)

Best regards,
-- 
Yann