[PATCH] format-patch: Update the `-3` example

In the EXAMPLES section, `git-format-patch -3` doesn't work
anymore. Update it to read `git format-patch HEAD~3`. The example was
introduced in 7c49628 and had not been updated since.

Signed-off-by: Ramkumar Ramachandra <redacted>
---
 Documentation/git-format-patch.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 4b3f5ba..2a44472 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt

@@ -271,7 +271,7 @@ use it only when you know the recipient uses git to apply your patch.
 as e-mailable patches:
 +
 ------------
-$ git format-patch -3
+$ git format-patch HEAD~3
 ------------
 
 SEE ALSO

-- 
1.7.2.2.409.gdbb11.dirty

Ramkumar Ramachandra [off-list ref] writes:

Works for me:

  5031:[gitweb/split@git]# git format-patch -3
  0001-gitweb-Prepare-for-splitting-gitweb.txt
  0002-gitweb-Create-Gitweb-Git-module.txt

  5034:[gitweb/split@git]# git version
  git version 1.7.2.1


The -3 is git-log option:

  -<n>   Limits the number of commits to show.

and also git-format-patch option:

  -<n>   Limits the number of patches to prepare.

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Hi Jakub,

Jakub Narebski writes:

Works for me:

  5031:[gitweb/split@git]# git format-patch -3
  0001-gitweb-Prepare-for-splitting-gitweb.txt
  0002-gitweb-Create-Gitweb-Git-module.txt

  5034:[gitweb/split@git]# git version
  git version 1.7.2.1


The -3 is git-log option:

  -<n>   Limits the number of commits to show.

and also git-format-patch option:

  -<n>   Limits the number of patches to prepare.

Hm, doesn't work on the `pu` Git, but works on `master` -- I'm
currently bisecting to find the problem. `git log -3` works
though.

-- Ram

Hi,

Ramkumar Ramachandra writes:

Hi Jakub,

Jakub Narebski writes:

quoted

Works for me:

  5031:[gitweb/split@git]# git format-patch -3
  0001-gitweb-Prepare-for-splitting-gitweb.txt
  0002-gitweb-Create-Gitweb-Git-module.txt

  5034:[gitweb/split@git]# git version
  git version 1.7.2.1


The -3 is git-log option:

  -<n>   Limits the number of commits to show.

and also git-format-patch option:

  -<n>   Limits the number of patches to prepare.

Hm, doesn't work on the `pu` Git, but works on `master` -- I'm
currently bisecting to find the problem. `git log -3` works
though.

:facepalm:

Scratch out what I just said -- I just realized that `git format-patch
HEAD~3` handles merge commits, but `git format-patch -3` does
not. `git format-patch -3 HEAD~3` is even more confusing- should we
even advertise the `-<n>` option in format-patch?

-- Ram

On Samstag, 21. August 2010, Ramkumar Ramachandra wrote:

should we
even advertise the `-<n>` option in format-patch?

Oh, yeah! IMHO, it is its most useful option.

-- Hannes

On Sat, 21 Aug 2010, Ramkumar Ramachandra wrote:

Ramkumar Ramachandra writes:

quoted

Jakub Narebski writes:

quoted

Works for me:

  5031:[gitweb/split@git]# git format-patch -3
  0001-gitweb-Prepare-for-splitting-gitweb.txt
  0002-gitweb-Create-Gitweb-Git-module.txt

  5034:[gitweb/split@git]# git version
  git version 1.7.2.1


The -3 is git-log option:

  -<n>   Limits the number of commits to show.

and also git-format-patch option:

  -<n>   Limits the number of patches to prepare.

Hm, doesn't work on the `pu` Git, but works on `master` -- I'm
currently bisecting to find the problem. `git log -3` works
though.

:facepalm:

Scratch out what I just said -- I just realized that `git format-patch
HEAD~3` handles merge commits, but `git format-patch -3` does
not. `git format-patch -3 HEAD~3` is even more confusing- should we
even advertise the `-<n>` option in format-patch?

It looks like there is a conceptual bug in how git-format-patch works, 
namely that '-<n>' is passed to rev-list / log generating machinery, 
and it limits number of *commits* to consider; if some of those commits 
are merge commits, which cannot be represented as patches, the number 
of patches it generates is less than specified <n> (as you can see in 
the example I have provided, where <n> == 3, and git-format-patch 
generated 2 patches, not 3).  In extreme case (like 'pu') it can 
generate no patch.

I am not sure what the solution should be.  We could either:

A. Update git-format-patch documentation to say 'commits' instead of
   'patches', and perhaps also be loud about commits we are skipping,
   so that my example would look e.g. like this:

     $ git format-patch -3
     0001-gitweb-Prepare-for-splitting-gitweb.txt
     0002-gitweb-Create-Gitweb-Git-module.txt
     Skipping merge commit: Merge branch 'maint'

or

B. Modify git-format-patch so that "git format-patch -<n>" would always
   generate <n> patches from specified commits, if there are that many.

But I think that option B.) it might be difficult, so perhaps A.) is 
"it". 
-- 
Jakub Narebski
Poland

Hi Jakub,

Jakub Narebski writes:

On Sat, 21 Aug 2010, Ramkumar Ramachandra wrote:

quoted

Ramkumar Ramachandra writes:

quoted

Jakub Narebski writes:

quoted

Works for me:

  5031:[gitweb/split@git]# git format-patch -3
  0001-gitweb-Prepare-for-splitting-gitweb.txt
  0002-gitweb-Create-Gitweb-Git-module.txt

  5034:[gitweb/split@git]# git version
  git version 1.7.2.1


The -3 is git-log option:

  -<n>   Limits the number of commits to show.

and also git-format-patch option:

  -<n>   Limits the number of patches to prepare.

Hm, doesn't work on the `pu` Git, but works on `master` -- I'm
currently bisecting to find the problem. `git log -3` works
though.

:facepalm:

Scratch out what I just said -- I just realized that `git format-patch
HEAD~3` handles merge commits, but `git format-patch -3` does
not. `git format-patch -3 HEAD~3` is even more confusing- should we
even advertise the `-<n>` option in format-patch?

It looks like there is a conceptual bug in how git-format-patch works, 
namely that '-<n>' is passed to rev-list / log generating machinery, 
and it limits number of *commits* to consider; if some of those commits 
are merge commits, which cannot be represented as patches, the number 
of patches it generates is less than specified <n> (as you can see in 
the example I have provided, where <n> == 3, and git-format-patch 
generated 2 patches, not 3).  In extreme case (like 'pu') it can 
generate no patch.

I am not sure what the solution should be.  We could either:

A. Update git-format-patch documentation to say 'commits' instead of
   'patches', and perhaps also be loud about commits we are skipping,
   so that my example would look e.g. like this:

     $ git format-patch -3
     0001-gitweb-Prepare-for-splitting-gitweb.txt
     0002-gitweb-Create-Gitweb-Git-module.txt
     Skipping merge commit: Merge branch 'maint'

Thanks for the awesome explanation! A is definitely the way to go-
I'll start writing a patch immediately.

-- Ram