fe77b416c7
Most of our documentation is in a single directory, so using
linkgit:git-config[1] just generates a relative link in the
same directory. However, this is not the case with the API
documentation in technical/*, which need to refer to
git-config from the parent directory.
We can fix this by passing a special prefix attribute when building
in a subdirectory, and respecting that prefix in our linkgit
definitions.
We only have to modify the html linkgit definition. For
manpages, we can ignore this for two reasons:
1. we do not generate actual links to the file in
manpages, but instead just give the name and section of
the linked manpage
2. we do not currently build manpages for subdirectories,
only html
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
105 lines
3.3 KiB
Plaintext
105 lines
3.3 KiB
Plaintext
merge API
|
|
=========
|
|
|
|
The merge API helps a program to reconcile two competing sets of
|
|
improvements to some files (e.g., unregistered changes from the work
|
|
tree versus changes involved in switching to a new branch), reporting
|
|
conflicts if found. The library called through this API is
|
|
responsible for a few things.
|
|
|
|
* determining which trees to merge (recursive ancestor consolidation);
|
|
|
|
* lining up corresponding files in the trees to be merged (rename
|
|
detection, subtree shifting), reporting edge cases like add/add
|
|
and rename/rename conflicts to the user;
|
|
|
|
* performing a three-way merge of corresponding files, taking
|
|
path-specific merge drivers (specified in `.gitattributes`)
|
|
into account.
|
|
|
|
Data structures
|
|
---------------
|
|
|
|
* `mmbuffer_t`, `mmfile_t`
|
|
|
|
These store data usable for use by the xdiff backend, for writing and
|
|
for reading, respectively. See `xdiff/xdiff.h` for the definitions
|
|
and `diff.c` for examples.
|
|
|
|
* `struct ll_merge_options`
|
|
|
|
This describes the set of options the calling program wants to affect
|
|
the operation of a low-level (single file) merge. Some options:
|
|
|
|
`virtual_ancestor`::
|
|
Behave as though this were part of a merge between common
|
|
ancestors in a recursive merge.
|
|
If a helper program is specified by the
|
|
`[merge "<driver>"] recursive` configuration, it will
|
|
be used (see linkgit:gitattributes[5]).
|
|
|
|
`variant`::
|
|
Resolve local conflicts automatically in favor
|
|
of one side or the other (as in 'git merge-file'
|
|
`--ours`/`--theirs`/`--union`). Can be `0`,
|
|
`XDL_MERGE_FAVOR_OURS`, `XDL_MERGE_FAVOR_THEIRS`, or
|
|
`XDL_MERGE_FAVOR_UNION`.
|
|
|
|
`renormalize`::
|
|
Resmudge and clean the "base", "theirs" and "ours" files
|
|
before merging. Use this when the merge is likely to have
|
|
overlapped with a change in smudge/clean or end-of-line
|
|
normalization rules.
|
|
|
|
Low-level (single file) merge
|
|
-----------------------------
|
|
|
|
`ll_merge`::
|
|
|
|
Perform a three-way single-file merge in core. This is
|
|
a thin wrapper around `xdl_merge` that takes the path and
|
|
any merge backend specified in `.gitattributes` or
|
|
`.git/info/attributes` into account. Returns 0 for a
|
|
clean merge.
|
|
|
|
Calling sequence:
|
|
|
|
* Prepare a `struct ll_merge_options` to record options.
|
|
If you have no special requests, skip this and pass `NULL`
|
|
as the `opts` parameter to use the default options.
|
|
|
|
* Allocate an mmbuffer_t variable for the result.
|
|
|
|
* Allocate and fill variables with the file's original content
|
|
and two modified versions (using `read_mmfile`, for example).
|
|
|
|
* Call `ll_merge()`.
|
|
|
|
* Read the merged content from `result_buf.ptr` and `result_buf.size`.
|
|
|
|
* Release buffers when finished. A simple
|
|
`free(ancestor.ptr); free(ours.ptr); free(theirs.ptr);
|
|
free(result_buf.ptr);` will do.
|
|
|
|
If the modifications do not merge cleanly, `ll_merge` will return a
|
|
nonzero value and `result_buf` will generally include a description of
|
|
the conflict bracketed by markers such as the traditional `<<<<<<<`
|
|
and `>>>>>>>`.
|
|
|
|
The `ancestor_label`, `our_label`, and `their_label` parameters are
|
|
used to label the different sides of a conflict if the merge driver
|
|
supports this.
|
|
|
|
Everything else
|
|
---------------
|
|
|
|
Talk about <merge-recursive.h> and merge_file():
|
|
|
|
- merge_trees() to merge with rename detection
|
|
- merge_recursive() for ancestor consolidation
|
|
- try_merge_command() for other strategies
|
|
- conflict format
|
|
- merge options
|
|
|
|
(Daniel, Miklos, Stephan, JC)
|