Re: What's in git.git (stable)

From: Junio C Hamano <hidden>
Date: 2016-08-11 19:37:51

quoted

I am hoping that we can start a stabilization cycle for v1.5.0
based on what we have in 'master'.  The theme is "usability and
teachability".

Things that need to be done to complete what have been merged to
'master' are:

 - 'git-rm' needs to be fixed up as Linus outlined; remove
   working tree file and index entry but have a sanity check to
   make sure the working tree file match the index and HEAD.

 - 'git-branch' may need to be taught about renaming the
   matching per-branch configuration at the same time.

 - 'git-merge-file' needs to be documented and linked from
   git.txt.

 - 'git-clone' probably should be updated to use wild-card in
   remote.origin.fetch, instead of listing all the branches it
   found when the clone was made.

 - tutorials and other Porcelain documentation pages need to be
   updated to match the updated 'git-add' and 'git-rm' (to be
   updated), and their description should be made much less
   about implementation; they should talk in terms of end-user
   workflows.  I will send a draft for 'git diff' out later, but
   somebody needs a full sweep on Porcelain-ish documentation.

 - 'git diff --index' patch should be reverted (already done in
   'next'), although we may have to come up with a better
   wording for --cached.

I'm done with 2 out of the above six ("diff --index", and
"clone") and a bit of the "documentation" item so far, and will
go to bed now.  Any takers for the remaining tasks while I'll be
sleeping ;-)?

[PATCH] Document git-merge-file

From: Johannes Schindelin <hidden>
Date: 2016-08-11 20:04:18

Most of this is derived from the documentation of RCS merge.

Signed-off-by: Johannes Schindelin <redacted>
---

	On Sat, 16 Dec 2006, Junio C Hamano wrote:

	> >>  - 'git-merge-file' needs to be documented and linked from
	> >>    git.txt.

 Documentation/git-merge-file.txt |   92 ++++++++++++++++++++++++++++++++++++++
 Documentation/git.txt            |    3 +
 2 files changed, 95 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt
new file mode 100644
index 0000000..0b41d66
--- /dev/null
+++ b/Documentation/git-merge-file.txt

@@ -0,0 +1,92 @@
+git-merge-file(1)
+============
+
+NAME
+----
+git-merge-file - threeway file merge
+
+
+SYNOPSIS
+--------
+[verse]
+'git-merge-file' [-L <current-name> [-L <base-name> [-L <other-name>]]]
+	[-p|--stdout] [-q|--quiet] <current-file> <base-file> <other-file>
+
+
+DESCRIPTION
+-----------
+git-file-merge incorporates all changes that lead from the `<base-file>`
+to `<other-file>` into `<current-file>`. The result ordinarily goes into
+`<current-file>`. git-merge-file is useful for combining separate changes
+to an original. Suppose `<base-file>` is the original, and both
+`<current-file>` and `<other-file>` are modifications of `<base-file>`.
+Then git-merge-file combines both changes.
+
+A conflict occurs if both `<current-file>` and `<other-file>` have changes
+in a common segment of lines. If a conflict is found, git-merge-file
+normally outputs a warning and brackets the conflict with <<<<<<< and
+>>>>>>> lines. A typical conflict will look like this:
+
+	<<<<<<< A
+	lines in file A
+	=======
+	lines in file B
+	>>>>>>> B
+
+If there are conflicts, the user should edit the result and delete one of
+the alternatives.
+
+The exit value of this program is negative on error, and the number of
+conflicts otherwise. If the merge was clean, the exit value is 0.
+
+git-merge-file is designed to be a minimal clone of RCS merge, that is, it
+implements all of RCS merge's functionality which is needed by
+gitlink:git[1].
+
+
+OPTIONS
+-------
+
+-L <label>::
+	This option may be given up to three times, and
+	specifies labels to be used in place of the
+	corresponding file names in conflict reports. That is,
+	`git-merge-file -L x -L y -L z a b c` generates output that
+	looks like it came from files x, y and z instead of
+	from files a, b and c.
+
+-p::
+	Send results to standard output instead of overwriting
+	`<current-file>`.
+
+-q::
+	Quiet;  do  not  warn about conflicts.
+
+
+EXAMPLES
+--------
+
+git merge-file README.my README README.upstream::
+
+	combines the changes of README.my and README.upstream since README,
+	tries to merge them and writes the result into README.my.
+
+git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345::
+
+	merges tmp/a123 and tmp/c345 with the base tmp/b234, but uses labels
+	`a` and `c` instead of `tmp/a123` and `tmp/c345`.
+
+
+Author
+------
+Written by Johannes Schindelin <johannes.schindelin@gmx.de>
+
+
+Documentation
+--------------
+Documentation by Johannes Schindelin and the git-list <git@vger.kernel.org>,
+with parts copied from the original documentation of RCS merge.
+
+GIT
+---
+Part of the gitlink:git[7] suite

diff --git a/Documentation/git.txt b/Documentation/git.txt
index b9b1e63..b9fc9ae 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt

@@ -359,6 +359,9 @@ gitlink:git-init-db[1]::
 	Creates an empty git object database, or reinitialize an
 	existing one.
 
+gitlink:git-merge-file[1]::
+	Runs a threeway merge.
+
 gitlink:git-merge-index[1]::
 	Runs a merge for files needing merging.

-- 
1.4.4.2.g5dc03

`h`	back out one level
`j`	next message in thread
`k`	previous message in thread
`l`	drill in
`Esc`	close help / fold thread tree
`?`	toggle this help