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

From: Nikolaj Shurkaev <snnicky@gmail.com>
Date: Mar 3, 2012, 13:41 UTC
Message-ID: <4F521F6E.2040602@gmail.com>
In-Reply-To: <20120224211658.GA30922@sigill.intra.peff.net>

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
>