FM / technical

/usr/share/doc/git/technical

Name	Size	Mode	Actions
api-error-handling.html	22259	0644	edit dl rm
api-error-handling.txt	3818	0644	edit dl rm
api-index-skel.txt	432	0644	edit dl rm
api-index.html	17183	0644	edit dl rm
api-index.sh	611	0644	edit dl rm
api-index.txt	648	0644	edit dl rm
api-merge.html	18305	0644	edit dl rm
api-merge.txt	1090	0644	edit dl rm
api-parse-options.html	36657	0644	edit dl rm
api-parse-options.txt	13157	0644	edit dl rm
api-simple-ipc.html	22388	0644	edit dl rm
api-simple-ipc.txt	4852	0644	edit dl rm
api-trace2.html	77619	0644	edit dl rm
api-trace2.txt	44255	0644	edit dl rm
bitmap-format.html	30403	0644	edit dl rm
bitmap-format.txt	8871	0644	edit dl rm
bundle-uri.html	51387	0644	edit dl rm
bundle-uri.txt	26787	0644	edit dl rm
commit-graph.txt	17957	0644	edit dl rm
directory-rename-detection.txt	5199	0644	edit dl rm
hash-function-transition.html	64539	0644	edit dl rm
hash-function-transition.txt	35894	0644	edit dl rm
long-running-process-protocol.html	18995	0644	edit dl rm
long-running-process-protocol.txt	1929	0644	edit dl rm
multi-pack-index.html	22462	0644	edit dl rm
multi-pack-index.txt	4459	0644	edit dl rm
pack-heuristics.html	43594	0644	edit dl rm
pack-heuristics.txt	18040	0644	edit dl rm
packfile-uri.txt	3748	0644	edit dl rm
parallel-checkout.html	31715	0644	edit dl rm
parallel-checkout.txt	12301	0644	edit dl rm
partial-clone.html	36496	0644	edit dl rm
partial-clone.txt	14968	0644	edit dl rm
racy-git.html	27995	0644	edit dl rm
racy-git.txt	9121	0644	edit dl rm
reftable.html	73792	0644	edit dl rm
reftable.txt	37525	0644	edit dl rm
remembering-renames.txt	30360	0644	edit dl rm
repository-version.txt	4311	0644	edit dl rm
rerere.txt	6510	0644	edit dl rm
scalar.html	20458	0644	edit dl rm
scalar.txt	2935	0644	edit dl rm
send-pack-pipeline.html	19315	0644	edit dl rm
send-pack-pipeline.txt	1969	0644	edit dl rm
shallow.html	19685	0644	edit dl rm
shallow.txt	2548	0644	edit dl rm
sparse-checkout.txt	47499	0644	edit dl rm
sparse-index.txt	9501	0644	edit dl rm
trivial-merge.html	22273	0644	edit dl rm
trivial-merge.txt	4264	0644	edit dl rm

Edit: /usr/share/doc/git/technical/trivial-merge.txt (4264B)

Trivial merge rules
===================

This document describes the outcomes of the trivial merge logic in read-tree.

One-way merge
-------------

This replaces the index with a different tree, keeping the stat info
for entries that don't change, and allowing -u to make the minimum
required changes to the working tree to have it match.

Entries marked '+' have stat information. Spaces marked '*' don't
affect the result.

index   tree    result
   -----------------------
   *       (empty) (empty)
   (empty) tree    tree
   index+  tree    tree
   index+  index   index+

Two-way merge
-------------

It is permitted for the index to lack an entry; this does not prevent
any case from applying.

If the index exists, it is an error for it not to match either the old
or the result.

If multiple cases apply, the one used is listed first.

A result which changes the index is an error if the index is not empty
and not up to date.

Entries marked '+' have stat information. Spaces marked '*' don't
affect the result.

case  index   old     new     result
 -------------------------------------
 0/2   (empty) *       (empty) (empty)
 1/3   (empty) *       new     new
 4/5   index+  (empty) (empty) index+
 6/7   index+  (empty) index   index+
 10    index+  index   (empty) (empty)
 14/15 index+  old     old     index+
 18/19 index+  old     index   index+
 20    index+  index   new     new

Three-way merge
---------------

It is permitted for the index to lack an entry; this does not prevent
any case from applying.

If the index exists, it is an error for it not to match either the
head or (if the merge is trivial) the result.

If multiple cases apply, the one used is listed first.

A result of "no merge" means that index is left in stage 0, ancest in
stage 1, head in stage 2, and remote in stage 3 (if any of these are
empty, no entry is left for that stage). Otherwise, the given entry is
left in stage 0, and there are no other entries.

A result of "no merge" is an error if the index is not empty and not
up to date.

*empty* means that the tree must not have a directory-file conflict
 with the entry.

For multiple ancestors, a '+' means that this case applies even if
only one ancestor or remote fits; a '^' means all of the ancestors
must be the same.

case  ancest    head    remote    result
 ----------------------------------------
 1     (empty)+  (empty) (empty)   (empty)
 2ALT  (empty)+  *empty* remote    remote
 2     (empty)^  (empty) remote    no merge
 3ALT  (empty)+  head    *empty*   head
 3     (empty)^  head    (empty)   no merge
 4     (empty)^  head    remote    no merge
 5ALT  *         head    head      head
 6     ancest+   (empty) (empty)   no merge
 8     ancest^   (empty) ancest    no merge
 7     ancest+   (empty) remote    no merge
 10    ancest^   ancest  (empty)   no merge
 9     ancest+   head    (empty)   no merge
 16    anc1/anc2 anc1    anc2      no merge
 13    ancest+   head    ancest    head
 14    ancest+   ancest  remote    remote
 11    ancest+   head    remote    no merge

Only #2ALT and #3ALT use *empty*, because these are the only cases
where there can be conflicts that didn't exist before. Note that we
allow directory-file conflicts between things in different stages
after the trivial merge.

A possible alternative for #6 is (empty), which would make it like
#1. This is not used, due to the likelihood that it arises due to
moving the file to multiple different locations or moving and deleting
it in different branches.

Case #1 is included for completeness, and also in case we decide to
put on '+' markings; any path that is never mentioned at all isn't
handled.

Note that #16 is when both #13 and #14 apply; in this case, we refuse
the trivial merge, because we can't tell from this data which is
right. This is a case of a reverted patch (in some direction, maybe
multiple times), and the right answer depends on looking at crossings
of history or common ancestors of the ancestors.

Note that, between #6, #7, #9, and #11, all cases not otherwise
covered are handled in this table.

For #8 and #10, there is alternative behavior, not currently
implemented, where the result is (empty). As currently implemented,
the automatic merge will generally give this effect.

cmd: