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

From: Shawn O. Pearce <spearce@spearce.org>
Date: Mar 23, 2008, 05:00 UTC
Message-ID: <20080323050028.GI8410@spearce.org>
In-Reply-To: <BDCF3EE6-0813-40B1-96D8-CCBADCCDAEA6@orakel.ntnu.no>

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.