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> Acked-by: Shawn O. Pearce <spearce@spearce.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Eyvind Bernhardsen committed Mar 21, 2008 at 16:25 UTC 9b33fa08b2d9507f8ffefe7649a59d23b4176185

1 file changed +8 -3

Documentation/git-fast-import.txt

+8 -3

@@ -385,6 +385,9 @@ new commit.

385 Omitting the `from` command in the first commit of a new branch

386 will cause fast-import to create that commit with no ancestor. This

387 tends to be desired only for the initial commit of a project.

388 +If the frontend creates all files from scratch when making a new

389 +branch, a `merge` command may be used instead of `from` to start

390 +the commit with an empty tree.

391 Omitting the `from` command on existing branches is usually desired,

392 as the current commit on that branch is automatically assumed to

393 be the first ancestor of the new commit.

@@ -427,13 +430,15 @@ existing value of the branch.

430

431 `merge`

432 ^^^^^^^

430 -Includes one additional ancestor commit, and makes the current

431 -commit a merge commit. An unlimited number of `merge` commands per

433 +Includes one additional ancestor commit. If the `from` command is

434 +omitted when creating a new branch, the first `merge` commit will be

435 +the first ancestor of the current commit, and the branch will start

436 +out with no files. An unlimited number of `merge` commands per

437 commit are permitted by fast-import, thereby establishing an n-way merge.

438 However Git's other tools never create commits with more than 15

439 additional ancestors (forming a 16-way merge). For this reason

440 it is suggested that frontends do not use more than 15 `merge`

436 -commands per commit.

441 +commands per commit; 16, if starting a new, empty branch.

442

443 Here `<committish>` is any of the commit specification expressions

444 also accepted by `from` (see above).