"commit"s without "from" in fast-import

"commit"s without "from" in fast-import

[Eyvind Bernhardsen]

Hi,

I have a question about fast-import, specifically a (possibly)  
unorthodox usage of it by cvs2svn.  Cvs2svn generates "commit"s with  
no "from" commands; instead, it emits a "merge" from the previous  
commit on the branch, and then rebuilds the entire state of the tree.

I've verified that the generated repositories are correct, so I know  
that it works, and I _think_ that it's equivalent to having "from  
<mark>" followed by "filedeleteall".

What I'm wondering is: is there any reason to modify cvs2svn's output  
to comply more to the man page's way of doing things, or is this a  
perfectly valid usage?
-- 
Eyvind Bernhardsen

Re: "commit"s without "from" in fast-import

[Shawn O. Pearce]

Eyvind Bernhardsen <eyvind-git@orakel.ntnu.no> wrote:
> I have a question about fast-import, specifically a (possibly)  
> unorthodox usage of it by cvs2svn.  Cvs2svn generates "commit"s with  
> no "from" commands; instead, it emits a "merge" from the previous  
> commit on the branch, and then rebuilds the entire state of the tree.
> 
> I've verified that the generated repositories are correct, so I know  
> that it works, and I _think_ that it's equivalent to having "from  
> <mark>" followed by "filedeleteall".

Hehe.  Cute trick.  Never intended for it to be used like that.
The git implementation of git-fast-import behaves as you describe,
but I do not know how bzr-fast-import would handle such a stream.

> What I'm wondering is: is there any reason to modify cvs2svn's output  
> to comply more to the man page's way of doing things, or is this a  
> perfectly valid usage?

In my opinion its an interesting use of the language.  The grammar
does not say that no merge commands are permitted when creating
a branch.  It wasn't what I intended, and is really a gap in the
grammar specification.  I'd prefer well known frontends use a
more conventional structure, just in case something were to ever
change about the implementation details of a given importer and
this command set break.  But that's just me.

Maybe we should make this more formalized in the documentation as
allowable, so if it does break for an importer the importer author
has to fix git-fast-import, bzr-fast-import, *-fast-import instead.

-- 
Shawn.

Re: "commit"s without "from" in fast-import

[Shawn O. Pearce]

Eyvind Bernhardsen <eyvind-git@orakel.ntnu.no> wrote:
> On 18. mars. 2008, at 04.43, Shawn O. Pearce wrote:
> [...]
> >Maybe we should make this more formalized in the documentation as
> >allowable, so if it does break for an importer the importer author
> >has to fix git-fast-import, bzr-fast-import, *-fast-import instead.
> 
> In the interests of language strictness, I think it should be  
> explicitly either allowed or forbidden, and if it is forbidden I think  
> fast-import should barf on it.

Agreed.
 
> From a git perspective it seems ok to allow it, since a commit is  
> only really a tree and a set of parent commits.  "from" adds a parent  
> and initialises the tree, "merge" adds a parent without touching the  
> tree.  But maybe I'm thinking too git-centrically.
> 
> I can try to make a documentation patch that allows it and see if  
> having it "on paper" makes it more or less reasonable.

I'm leaning towards leaving it in the language as allowed, and thus
documenting that this is not only possible, but actively used by
importers as it can be an easy way to setup a subsequent change
with no initial files.

But I have to wonder what the bzr-fast-import folks would say.
I've CC'd in James and Ian, as they have been working on the bzr
side for a little.

James, Ian -- to give you the short backstory we are talking about
creating a new branch _without_ a "from", but instead using a single
"merge" to specify the sole ancestor revision of a new commit to
be placed on the new branch.  This allows the frontend to supply
all files for the tree as none were inherited from the sole ancestor.

The other (more obvious?) approach to accomplish the same result
is to use "from" followed by a "filedeleteall" to clear the files,
then supply the new files.  Both approaches have the exact same
result in git-fast-import.

-- 
Shawn.

Re: "commit"s without "from" in fast-import

[James Westby]

On Tue, 2008-03-18 at 22:06 -0400, Shawn O. Pearce wrote:
> James, Ian -- to give you the short backstory we are talking about
> creating a new branch _without_ a "from", but instead using a single
> "merge" to specify the sole ancestor revision of a new commit to
> be placed on the new branch.  This allows the frontend to supply
> all files for the tree as none were inherited from the sole ancestor.
> 
> The other (more obvious?) approach to accomplish the same result
> is to use "from" followed by a "filedeleteall" to clear the files,
> then supply the new files.  Both approaches have the exact same
> result in git-fast-import.
> 

I don't see why this would cause a fundamental problem for 
bzr-fastimport, and shouldn't be difficult to implement, so I'm
happy for you to proceed however you like.

Thanks,

James

Re: [PATCH] fast-import: Document the effect of "merge" with no "from" in a commit

[Shawn O. Pearce]

Eyvind Bernhardsen <eyvind-git@orakel.ntnu.no> wrote:
> @@ -385,9 +385,11 @@ new commit.
>  Omitting the `from` command in the first commit of a new branch
>  will cause fast-import to create that commit with no ancestor. This
>  tends to be desired only for the initial commit of a project.
> -Omitting the `from` command on existing branches is usually desired,
> +Including the `from` command on existing branches is usually desired,
>  as the current commit on that branch is automatically assumed to
>  be the first ancestor of the new commit.

I disagree with this.  Omitting is the correct term here as you
usually do not want a 'from' commit, as you usually want it to
automatically use the prior commit made on this branch.

As I understand it, this discussion about leaving out 'from' and
using 'merge' is only relevant on a *new* branch.

> +If the frontend creates all files from scratch when making a new
> +commit, a `merge` command may be used instead.

This is fine.
 
>  As `LF` is not valid in a Git refname or SHA-1 expression, no
>  quoting or escaping syntax is supported within `<committish>`.
> @@ -427,13 +429,15 @@ existing value of the branch.
> 
>  `merge`
>  ^^^^^^^
> -Includes one additional ancestor commit, and makes the current
> -commit a merge commit.  An unlimited number of `merge` commands per
> +Includes one additional ancestor commit.  In the absence of a `from`
> +command, the first `merge` commit will be the first ancestor of the
> +current commit, and the commit will start out with no files.  An
> +unlimited number of `merge` commands per
>  commit are permitted by fast-import, thereby establishing an n-way  
> merge.
>  However Git's other tools never create commits with more than 15
>  additional ancestors (forming a 16-way merge).  For this reason
>  it is suggested that frontends do not use more than 15 `merge`
> -commands per commit.
> +commands per commit; 16, if `from` is not used.

These updates are also fine.

-- 
Shawn.

Re: [PATCH] fast-import: Document the effect of "merge" with no "from" in a commit

[Eyvind Bernhardsen]

On 20. mars. 2008, at 11.43, Eyvind Bernhardsen wrote:
> On 20. mars. 2008, at 04.40, Shawn O. Pearce wrote:
>> As I understand it, this discussion about leaving out 'from' and
>> using 'merge' is only relevant on a *new* branch.
>
> Ah.  Unfortunately, that means that I don't understand why cvs2svn  
> works; it never removes files when creating a commit, even for an  
> existing branch, so I assumed that a "from" was required to populate  
> the tree.  I'll do some more testing to see what's going on.

It turns out that I'm an idiot and you're right.  I'll rewrite the  
patch to reflect that the "merge" behaviour only applies when creating  
a branch.
-- 
Eyvind Bernhardsen

[PATCH v2] fast-import: Document the effect of "merge" with no "from" in a commit

[Eyvind Bernhardsen]

The fast-import documentation currently does not document the behaviour
of "merge" when there is no "from" in a commit.  This patch adds a
description of what happens: the commit is created with a parent, but
no files.  This behaviour is equivalent to "from" followed by
"filedeleteall".

Signed-off-by: Eyvind Bernhardsen <eyvind-git@orakel.ntnu.no>
---
On 21. mars. 2008, at 14.57, Eyvind Bernhardsen wrote:
> It turns out that I'm an idiot and you're right.  I'll rewrite the  
> patch to reflect that the "merge" behaviour only applies when  
> creating a branch.

Second attempt, now with 58% more understanding.

  Documentation/git-fast-import.txt |   11 ++++++++---
  1 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-fast-import.txt b/Documentation/git- 
fast-import.txt
index 96f6767..c29a4f8 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -385,6 +385,9 @@ new commit.
  Omitting the `from` command in the first commit of a new branch
  will cause fast-import to create that commit with no ancestor. This
  tends to be desired only for the initial commit of a project.
+If the frontend creates all files from scratch when making a new
+branch, a `merge` command may be used instead of `from` to start
+the commit with an empty tree.
  Omitting the `from` command on existing branches is usually desired,
  as the current commit on that branch is automatically assumed to
  be the first ancestor of the new commit.
@@ -427,13 +430,15 @@ existing value of the branch.

  `merge`
  ^^^^^^^
-Includes one additional ancestor commit, and makes the current
-commit a merge commit.  An unlimited number of `merge` commands per
+Includes one additional ancestor commit.  If the `from` command is
+omitted when creating a new branch, the first `merge` commit will be
+the first ancestor of the current commit, and the branch will start
+out with no files.  An unlimited number of `merge` commands per
  commit are permitted by fast-import, thereby establishing an n-way  
merge.
  However Git's other tools never create commits with more than 15
  additional ancestors (forming a 16-way merge).  For this reason
  it is suggested that frontends do not use more than 15 `merge`
-commands per commit.
+commands per commit; 16, if starting a new, empty branch.

  Here `<committish>` is any of the commit specification expressions
  also accepted by `from` (see above).
-- 
1.5.5.rc0.9.g6e103

Re: [PATCH v2] fast-import: Document the effect of "merge" with no "from" in a commit

[Shawn O. Pearce]

Eyvind Bernhardsen <eyvind-git@orakel.ntnu.no> wrote:
> The fast-import documentation currently does not document the behaviour
> of "merge" when there is no "from" in a commit.  This patch adds a
> description of what happens: the commit is created with a parent, but
> no files.  This behaviour is equivalent to "from" followed by
> "filedeleteall".
> 
> Signed-off-by: Eyvind Bernhardsen <eyvind-git@orakel.ntnu.no>

Thanks.  This change does clarify the documentation.

Acked-by: Shawn O. Pearce <spearce@spearce.org>


> diff --git a/Documentation/git-fast-import.txt b/Documentation/git- 
> fast-import.txt
> index 96f6767..c29a4f8 100644
> --- a/Documentation/git-fast-import.txt
> +++ b/Documentation/git-fast-import.txt
> @@ -385,6 +385,9 @@ new commit.
>  Omitting the `from` command in the first commit of a new branch
>  will cause fast-import to create that commit with no ancestor. This
>  tends to be desired only for the initial commit of a project.
> +If the frontend creates all files from scratch when making a new
> +branch, a `merge` command may be used instead of `from` to start
> +the commit with an empty tree.
>  Omitting the `from` command on existing branches is usually desired,
>  as the current commit on that branch is automatically assumed to
>  be the first ancestor of the new commit.
> @@ -427,13 +430,15 @@ existing value of the branch.
> 
>  `merge`
>  ^^^^^^^
> -Includes one additional ancestor commit, and makes the current
> -commit a merge commit.  An unlimited number of `merge` commands per
> +Includes one additional ancestor commit.  If the `from` command is
> +omitted when creating a new branch, the first `merge` commit will be
> +the first ancestor of the current commit, and the branch will start
> +out with no files.  An unlimited number of `merge` commands per
>  commit are permitted by fast-import, thereby establishing an n-way  
> merge.
>  However Git's other tools never create commits with more than 15
>  additional ancestors (forming a 16-way merge).  For this reason
>  it is suggested that frontends do not use more than 15 `merge`
> -commands per commit.
> +commands per commit; 16, if starting a new, empty branch.
> 
>  Here `<committish>` is any of the commit specification expressions
>  also accepted by `from` (see above).
> -- 
> 1.5.5.rc0.9.g6e103
> 

-- 
Shawn.

Re: [PATCH v2] fast-import: Document the effect of "merge" with no "from" in a commit

[Junio C Hamano]

Thanks, both.