threads / discuss / 12729

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

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

## tl;dr

9 messages between Mar 17, 2008 and Mar 23, 2008.

replies: 8people: 4as markdown or json

Eyvind Bernhardsen· Mar 17, 2008, 22:10 UTC · lore
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
Shawn O. Pearce· Mar 18, 2008, 03:43 UTC · re: Eyvind Bernhardsen · lore

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

Eyvind Bernhardsen <eyvind-git@orakel.ntnu.no> wrote:
Show 8 quoted lines
> 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.
Shawn O. Pearce· Mar 19, 2008, 02:06 UTC · lore

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

Eyvind Bernhardsen <eyvind-git@orakel.ntnu.no> wrote:
Show 9 quoted lines
> 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.
Show 7 quoted lines
> 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.
James Westby· Mar 19, 2008, 18:39 UTC · re: Shawn O. Pearce · lore

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

On Tue, 2008-03-18 at 22:06 -0400, Shawn O. Pearce wrote:
Show 11 quoted lines
> 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
Shawn O. Pearce· Mar 20, 2008, 03:40 UTC · lore

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

Eyvind Bernhardsen <eyvind-git@orakel.ntnu.no> wrote:
Show 8 quoted lines
> @@ -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.
Show 19 quoted lines
>  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.
Eyvind Bernhardsen· Mar 21, 2008, 13:57 UTC · lore

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

On 20. mars. 2008, at 11.43, Eyvind Bernhardsen wrote:
Show 8 quoted lines
> 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
Eyvind Bernhardsen· Mar 21, 2008, 15:25 UTC · re: Eyvind Bernhardsen · lore

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

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
Shawn O. Pearce· Mar 23, 2008, 05:00 UTC · re: Eyvind Bernhardsen · lore

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

Eyvind Bernhardsen <eyvind-git@orakel.ntnu.no> wrote:
Show 7 quoted lines
> 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>
Show 38 quoted lines
> 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.

← back to recent threads