Re: git log -z doesn't separate commits with NULs

[Nikolaj Shurkaev <snnicky@gmail.com>]

As far as I understood from what I read and from a brief look at source 
code of git (builtin/log.c file) the best what we can do is just mention 
that a lot of log options are applicable and warn user to use them with 
understanding of the consequences. I do not think that documentation of 
some of options in Documentation/git-format-patch.txt makes sense 
because some of the options are connected one with another. For example 
--full-diff and <path> are connected as Junio C Hamano wrote. And that 
dependency is already explained in Documentation/git-log.txt.

Another option that I see is to put git-log options description into a 
separate file and include that from git-log.txt and from 
git-format-patch.txt like that is done with rev-list-options.txt. That 
could be useful in a long term. Because new options may appear or some 
may disappear. Some dependency between options may be documented. 
However for me that would require to get better understanding how all 
that documentation is built. And that could require modifications of 
git-log help also.

Please let me know how to proceed with that properly. Perhaps I should 
start a separate discussion thread devoted to the documentation 
enhancement. Does thread subject matter?

Thank you.
----------------------
diff --git a/Documentation/git-format-patch.txt 
b/Documentation/git-format-patch.txt
index 6ea9be7..d49ec80 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -68,6 +68,15 @@ If given `--thread`, `git-format-patch` will generate 
`In-Reply-To` and
  as replies to the first mail; this also generates a `Message-Id` header to
  reference.

+NOTES
+-----
+
+`git format-patch` and `git log` share significant part of their
+implementations. As a result a lot of options available and described for
+`git log` will work for `git format-patch` also. However it's required to
+use them carefully with understanding of the consequences. For example
+applying `<path>` option may make log messages irrelevant.
+
  OPTIONS
  -------
  :git-format-patch: 1


25.02.2012 0:16, Jeff King пишет:
> On Fri, Feb 24, 2012 at 01:14:05PM -0800, Junio C Hamano wrote:
>
>>> True. That is also a slightly dangerous thing to do, though, because you
>>> are omitting full patches in the middle that touch the same paths as the
>>> patches you include....
>>> ... So
>>> perhaps we are better off to refer the user to git-log(1), say that
>>> commit limiting options in general would work, but be careful with
>>> sending a partial result.
>> You seem to have spelled out everything I originally wrote in my reply
>> that I later deleted before sending it out, and I think the reason that
>> brought you to the three-line conclusion is the same one that made me I
>> delete them ;-).
> OK, good. :)
>
> Nikolaj, have you followed all of this? Do you want to try to improve
> your patch in this direction?
>
> -Peff
>