Web lists-archives.com

Documentation for git-diff is very difficult to understand for a layman.




Hello, honourable GIT developers.

I would like to kindly ask you to do something with the git-diff
manpage. (https://git-scm.com/docs/git-diff)

In fact, I wasn't able to understand it even after reading it a few times.

In my case, I was trying to understand, what the command actually
prints, but the man page doesn't really tell that.

1)I mean, there is a section:

"https://git-scm.com/docs/git-diff#_combined_diff_format";, but at the
very end of the manpage, so presumably, only aimed at advanced users.
And the first thing it says is

"Any diff-generating command can take the -c or --cc option to produce
a combined diff when showing a merge. This is the default format when
showing merges with git-diff[1] ".

This line is confusing, because I am already actually running git-diff
(!). So am I really seeing a 'combined diff' or some other diff? Is
'git-diff' any different from 'git-diff -c' or 'git-diff -cc' ?

Could something be added to or rewritten in the manpage to clarify?

2)Also, in point 3 of the same section:

'index <hash>,<hash>..<hash>
mode <mode>,<mode>..<mode>
new file mode <mode>
deleted file mode <mode>,<mode>'

What do 'mode' and 'index' mean? Which values may this macros contain?
What do two dots '..' between two hashes mean? What are this hashes
of?
(Same question for <mode>.)

3)Same section, after point 4.

'Unlike the traditional unified diff format'. What is the 'traditional
unified diff'? Is it the diff produced by GNU diff, POSIX diff or
unidiff? Or, maybe there is some other diff in other parts of GIT?

4)There is also a section called 'other diff formats':
https://git-scm.com/docs/git-diff#_other_diff_formats

But it doesn't actually tell anything about other diff formats, it
just describes some other options to git-diff.

Maybe I am asking something trivial, but I believe, I am not the only
novice trying to read the documentation of git. (I found the man page
reference at the ProGIT book.)

5)Also, there is a contradiction in the documentation.

The first lines at the 'options'
(https://git-scm.com/docs/git-diff#_options) section say:

-p
-u
--patch

Generate patch (see section on generating patches). This is the default.

But at the 'combined diff' section:
(https://git-scm.com/docs/git-diff#_combined_diff_format)

The lines at the point 4 say:

"Chunk header format is modified to prevent people from accidentally
feeding it to patch -p1."

So what is in reality the behaviour of git-diff? Is it to create a
patch, or to prevent the creation of a patch?


I would be happy if some of the developers could (if not simplify the
man page), at least add some references at any manuals written in a
more newbie-friendly way.

Thank you in advance!


-- 
Yours sincerely, Vladimir Nikishkin