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

["Shawn O. Pearce" <spearce@spearce.org>]

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.