From: Thiago Perrotta <tbperrotta@xxxxxxxxx> The use of <rev-list options> in format-patch is confusing because it is meant to represent instead a subset of options from format-patch and a revision range. Change the documentation from both git send-email and format-patch to better describe the list of options that are expected. Signed-off-by: Carlo Marcelo Arenas Belón <carenas@xxxxxxxxx> --- This is an alternative to patch 3 which include most of the suggestions by Junio and Bagas, while also trying to minimize the change or the need to link to even more pages (which is why the suggestion[1] to link/use rev-list options was avoided). I expect it to be consistent and clear, but might had gotten some of the terminology wrong, and probably could have better grammar, so hoping for some feedback to improve on that. [1] https://lore.kernel.org/git/CABOtWuqXS_kJk2md=kgg-ReaWtKermpUW_Dk_bc0pMXQL+xMeA@xxxxxxxxxxxxxx/T/#m396f2a42936ec9a3191658d4b40d9043dfbc59e2 Documentation/git-format-patch.txt | 20 +++++++++++--------- Documentation/git-send-email.txt | 7 ++++--- 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index fe2f69d36e..fa2377d5e9 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -64,15 +64,17 @@ There are two ways to specify which commits to operate on. to the tip of the current branch that are not in the history that leads to the <since> to be output. -2. Generic <revision range> expression (see "SPECIFYING - REVISIONS" section in linkgit:gitrevisions[7]) means the - commits in the specified range. - -The first rule takes precedence in the case of a single <commit>. To -apply the second rule, i.e., format everything since the beginning of -history up until <commit>, use the `--root` option: `git format-patch ---root <commit>`. If you want to format only <commit> itself, you -can do this with `git format-patch -1 <commit>`. +2. A Generic <revision range> expression that describes with + options and revisions a range of commits. + +If you give a single <commit> and nothing else, it is taken as the +<since> of the first form. If you want to format everything since the +beginning of history up until <commit>, use the `--root` option: +`git format-patch --root <commit>`. If you want to format only the +<commit> itself, use instead `git format-patch -1 <commit>`. + +If you want to affect a set of commits, provide a range (see +"SPECIFYING RANGES" section in linkgit:gitrevisions[7]). By default, each output file is numbered sequentially from 1, and uses the first line of the commit message (massaged for pathname safety) as diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 3db4eab4ba..16d8d19cf5 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -9,7 +9,8 @@ git-send-email - Send a collection of patches as emails SYNOPSIS -------- [verse] -'git send-email' [<options>] <file|directory|rev-list options>... +'git send-email' [<send-email options>] <file|directory>... +'git send-email' [<send-email options>] <format-patch options> 'git send-email' --dump-aliases @@ -18,8 +19,8 @@ DESCRIPTION Takes the patches given on the command line and emails them out. Patches can be specified as files, directories (which will send all files in the directory), or directly as a revision list. In the -last case, any format accepted by linkgit:git-format-patch[1] can -be passed to git send-email. +last case, a revision in a format accepted by linkgit:git-format-patch[1] +as well as relevant options must be provided to git send-email. The header of the email is configurable via command-line options. If not specified on the command line, the user will be prompted with a ReadLine -- 2.33.0.1081.g099423f5b7
