[PATCH 0/2] core-git documentation update

[PATCH 0/2] core-git documentation update

[David Greaves]

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

-- 

Re: [PATCH 0/2] core-git documentation update

[Junio C Hamano]

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

Re: [PATCH 0/2] core-git documentation update

[David Greaves]

Junio C Hamano wrote:

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


-- 

Re: [PATCH 0/2] core-git documentation update

[Junio C Hamano]

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)
--- a/Documentation/core-git.txt
+++ b/Documentation/core-git.txt
@@ -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.
 

Re: [PATCH 0/2] core-git documentation update

[David Greaves]

[-- Attachment #1: Type: text/plain, Size: 1226 bytes --]

Junio C Hamano wrote:

>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.
>  
>
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?

>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?
>  
>
yes - that was just to assist people in reading the docs without having
to apply patches etc etc.

>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.
>  
>
I had hoped you'd pick this up in that manner - thanks

David
PS Removed Linus from cc

Add quotes for editorial consistency

Signed-off-by: David Greaves <david@dgreaves.com>
---




[-- Attachment #2: core-git_editorial.patch --]
[-- Type: text/x-patch, Size: 614 bytes --]

Documentation/core-git.txt: needs update
Index: Documentation/core-git.txt
===================================================================
--- 08cd7ce14ca4da7db37dce88e416e67b01f3452a/Documentation/core-git.txt  (mode:100644 sha1:e046119fcdd948dec81b11376ec9198e76a109af)
+++ uncommitted/Documentation/core-git.txt  (mode:100644)
@@ -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

Re: [PATCH 0/2] core-git documentation update

[Junio C Hamano]

>>>>> "DG" == David Greaves <david@dgreaves.com> writes:

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.