[PATCH] Docs: Add some missing options to git-diff.txt

[PATCH] Docs: Add some missing options to git-diff.txt

[Andreas Heiduk]

git-diff understands "--ours", "--theirs" and "--base" for files with
conflicts. But so far they were not documented for the central diff
command but only for diff-files.

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/git-diff.txt | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index bbab35f..91ced4f 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -97,6 +97,14 @@ OPTIONS
 :git-diff: 1
 include::diff-options.txt[]
 
+-1 --base::
+-2 --ours::
+-3 --theirs::
+-0::
+	Diff against the "base" version, "our branch" or "their
+	branch" respectively. The option -0 can be given to omit diff
+	output for unmerged entries and just show "Unmerged".
+
 <path>...::
 	The <paths> parameters, when given, are used to limit
 	the diff to the named paths (you can give directory
-- 
2.7.4

Re: [PATCH] Docs: Add some missing options to git-diff.txt

[Junio C Hamano]

Andreas Heiduk <asheiduk@gmail.com> writes:

> git-diff understands "--ours", "--theirs" and "--base" for files with
> conflicts. But so far they were not documented for the central diff
> command but only for diff-files.

This is probably a shared issue with the original text for
"diff-files", but I think we must stress that these options make
sense only when you are in the middle of conflict resolution.  

In addition, unlike "diff-files", if these were to appear in the
general "git diff" documentation, it also must stress that these
options are only about comparing the index and the working tree
files, e.g. "git diff --ours HEAD^ HEAD" does not make sense.

[PATCH v2] Docs: Add some missing options to git-diff.txt

[Andreas Heiduk]

New attempt due to whitespace fixes after EndOfSenctence.

Junio C Hamano writes:
> This is probably a shared issue with the original text for
> "diff-files", but I think we must stress that these options make
> sense only when you are in the middle of conflict resolution.  
>
> In addition, unlike "diff-files", if these were to appear in the
> general "git diff" documentation, it also must stress that these
> options are only about comparing the index and the working tree
> files, e.g. "git diff --ours HEAD^ HEAD" does not make sense.

Well, this wording picks up your points but I won't call it "stress
it" :-) However this should do the job.


------- 8< -------------------------- >8 -------------
git-diff understands "--ours", "--theirs" and "--base" for files with
conflicts. But so far they were not documented for the central diff
command but only for diff-files.

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/git-diff.txt | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index bbab35fca..b0c1bb95c 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -97,6 +97,20 @@ OPTIONS
 :git-diff: 1
 include::diff-options.txt[]
 
+-1 --base::
+-2 --ours::
+-3 --theirs::
+	Compare the working tree with the "base" version (stage #1),
+	"our branch" (stage #2) or "their branch" (stage #3).  The
+	index contains these stages only for unmerged entries i.e.
+	while resolving conflicts.  See linkgit:git-read-tree[1]
+	section "3-Way Merge" for detailed information.
+
+-0::
+	Omit diff output for unmerged entries and just show
+	"Unmerged".  Can be used only when comparing the working tree
+	with the index.
+
 <path>...::
 	The <paths> parameters, when given, are used to limit
 	the diff to the named paths (you can give directory
-- 
2.12.2

[PATCH v1] Docs: Add some missing options to git-diff.txt

[Andreas Heiduk]

Well, this wording picks up your points but I won't call it "stress
it" :-) However this should do the job.

--8<------>8------
git-diff understands "--ours", "--theirs" and "--base" for files with
conflicts. But so far they were not documented for the central diff
command but only for diff-files.

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/git-diff.txt | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index bbab35fca..2bccf4505 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -97,6 +97,21 @@ OPTIONS
 :git-diff: 1
 include::diff-options.txt[]
 
+-1 --base::
+-2 --ours::
+-3 --theirs::
+	Compare the working tree with the "base" version (stage #1),
+	"our branch" (stage #2) or "their branch" (stage #3). The
+	index contains these stages only for unmerged entries i.e.
+	while resolving conflicts.  See linkgit:git-read-tree[1]
+	section "3-Way Merge" for more information.
+
+-0::
+	Omit diff output for unmerged entries and just show
+	"Unmerged". Can be used only when comparing the working tree
+	with the index
+
+
 <path>...::
 	The <paths> parameters, when given, are used to limit
 	the diff to the named paths (you can give directory
-- 
2.12.2