core-git documentation update

Hi Linus, Junio

Here's an update of the core-git docs. I haven't changed the content - just the format.

1/2 was just sorting the core-git into alphabetical order. 2/2 is a complete reformat to asciidoc format. This includes a splitter to create individual txt, html and man pages.

David

David, thanks for taking time to update the document. I ended up hand merging your two patches since I had a bit more documentation updates in git-jc tree, so I'd like you to proofread the result.

It is my understanding that if I have a correct patch result from your patch 1 and patch 2, I can throw away this message:

Subject: [FILES] core-git documentation update

Am I correct?

I intend to keep not-so-controvercial stuff in git-jc tree, so that when Linus returns he can pull from it instead of patching from a pile of e-mails, potentially risking to leave good stuff in his mailbox during that process.

The following diff is between:

- Linus tree with two patches from you
+ The result of my hand merge, which I intend to ask Linus to pull when he returns.

Thanks.
---

# - 2: As Greaves
# + (working tree)

@@ -473,7 +473,7 @@ git-diff-cache - Compares content and mo
 
 SYNOPSIS
 --------
-'git-diff-cache' [-p] [-r] [-z] [--cached] <tree-ish>
+'git-diff-cache' [-p] [-r] [-z] [-m] [--cached] <tree-ish>
 
 DESCRIPTION
 -----------

@@ -500,6 +500,12 @@ OPTIONS
 --cached::
 	do not consider the on-disk file at all
 
+-m::
+	By default, files recorded in the index but not checked
+	out are reported as deleted.  This flag makes
+	git-diff-cache say that all non-checked-out files are up
+	to date.
+
 Output format
 -------------
 include::diff-format.txt[]

@@ -1515,7 +1521,7 @@ git-update-cache - Modifies the index or
 SYNOPSIS
 --------
 'git-update-cache'
-	     [--add] [--remove] [--refresh]
+	     [--add] [--remove] [--refresh] [--replace]
 	     [--ignore-missing]
 	     [--force-remove <file>]
 	     [--cacheinfo <mode> <object> <file>]\*

@@ -1556,6 +1562,14 @@ OPTIONS
 	Remove the file from the index even when the working directory
 	still has such a file.
 
+--replace::
+	By default, when a file `path` exists in the index,
+	git-update-cache refuses an attempt to add `path/file`.
+	Similarly if a file `path/file` exists, a file `path`
+	cannot be added.  With --replace flag, existing entries
+	that conflicts with the entry being added are
+	automatically removed with warning messages.
+
 --::
 	Do not interpret any more arguments as options.
 

This merged fine.
Purely for editorial consistency I added "" around the command - see patch

The intention now was for me to go through Linus' HEAD and verify the docs actually documented the HEAD.
Then I think comparing the HEAD to jit-jc and preparing patches for that?

yes - that was just to assist people in reading the docs without having to apply patches etc etc.

I had hoped you'd pick this up in that manner - thanks

David
PS Removed Linus from cc

Add quotes for editorial consistency

---

Documentation/core-git.txt: needs update
Index: Documentation/core-git.txt
===================================================================

@@ -503,7 +503,7 @@
 -m::
 	By default, files recorded in the index but not checked
 	out are reported as deleted.  This flag makes
-	git-diff-cache say that all non-checked-out files are up
+	"git-diff-cache" say that all non-checked-out files are up
 	to date.
 
 Output format

DG> The intention now was for me to go through Linus' HEAD and verify the DG> docs actually documented the HEAD.
DG> Then I think comparing the HEAD to jit-jc and preparing patches for that?

That one is up to you, but if your patches are against git-jc, it would make _my_ life simpler and hopefully would make merge easier for Linus when he returns.

After he returns, it would probably not make much sense sending patch against git-jc, unless all of the following conditions hold true: (1) what is already merged to git-jc conflicts with what you are modifying, (2) all changes in git-jc are trivially correct and veriy likely to hit Linus tree without being rejected, and (3) Linus is too busy and lags behind git-jc.

Quick question. Is this against the tip of Linus tree?

yes