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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html