Hi, On November 3, 2017 2:43:03 AM PDT, Vladimir Nikishkin <lockywolf@xxxxxxxxx> wrote: >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. Many parts of the man page are written from a very technical perspective. I'm sure patches to improve this would be welcome by the community. Even just reading your thoughts here is helpful, though I do not know who may find the interest and time to produce such. > >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 > The combined diff format is not a valid patch (as considered by the patch program) as it does not show how to convert from one file to another. Instead it's a way of showing the relevant differences between a resulting file and more than one input file, such as a merge would produce. >"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] ". > I suspect this is due to how parts of documentation are shared. The -c and -cc options can be given to many commands such as diff, log, show, etc >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' ? Yes, -c will cause git to always produce a combined diff format even for non merge states. > >Could something be added to or rewritten in the manpage to clarify? Suggestions are indeed welcome! > >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>.) > These I'm not sure about, they are bits of the diff we produce to give more context about the exact state of the changed files. >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? The traditional unified format is what's produced by the normal diff program when -U is given. This entire section is referring to extra headers we produce with our unified format. > >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. > Each of those options refers to a different diff format. >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.) Indeed, it's not trivial but it is important that our documentation is helpful. Perhaps we might want to move the more technical parts to their own section or to a separate page..? > >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." > The combined format is different because it fundamentally cannot be used as a patch, since it's output does not provide enough context as it's meant to show the difference between more than 2 states. It is meant to show what changed with respect to multiple parent copies of a file such as what happens in a merge. >So what is in reality the behaviour of git-diff? Is it to create a >patch, or to prevent the creation of a patch? > Git diff is meant to show differences between states. Much of the time this is in the form of patches but not always. > >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! Suggestions are definitely welcome. I don't offhand have links to more newbie friendly pages. I do agree many parts of the man page are less clear if you don't have a background in the tool already. Maybe we need to move the technical format bits to their own page and keep the more daily use aspects easier to find... Thanks Jake -- Sent from my Android device with K-9 Mail. Please excuse my brevity.
