threads / patch / 24816

patchformat-patch: Update the `-3` example

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

## tl;dr

7 messages between Aug 21, 2010 and Aug 21, 2010. Diffs are folded; open one to read it.

replies: 6people: 3as markdown or json

Ramkumar Ramachandra· Aug 21, 2010, 09:26 UTC · lore

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 <artagnon@gmail.com>
---
 Documentation/git-format-patch.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)
Show changes to Documentation/git-format-patch.txt +1 −1
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
Jakub Narebski· Aug 21, 2010, 10:23 UTC · re: Ramkumar Ramachandra · lore

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

Ramkumar Ramachandra <artagnon@gmail.com> writes:
Show 20 quoted lines
> 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 <artagnon@gmail.com>
> ---
>  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
>  ------------
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
Ramkumar Ramachandra· Aug 21, 2010, 10:34 UTC · re: Jakub Narebski · lore

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

Hi Jakub,
Jakub Narebski writes:
Show 17 quoted lines
> 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
Ramkumar Ramachandra· Aug 21, 2010, 10:53 UTC · re: Ramkumar Ramachandra · lore

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

Hi,
Ramkumar Ramachandra writes:
Show 24 quoted lines
> 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.
: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
Jakub Narebski· Aug 21, 2010, 14:59 UTC · re: Ramkumar Ramachandra · lore

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

On Sat, 21 Aug 2010, Ramkumar Ramachandra wrote:
Show 30 quoted lines
> Ramkumar Ramachandra writes:
> > 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.
> 
> :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
Ramkumar Ramachandra· Aug 21, 2010, 16:49 UTC · re: Jakub Narebski · lore

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

Hi Jakub,
Jakub Narebski writes:
Show 51 quoted lines
> On Sat, 21 Aug 2010, Ramkumar Ramachandra wrote:
> > Ramkumar Ramachandra writes:
> > > 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.
> > 
> > :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

← back to recent threads