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
