Re: How to create the " [PATCH 0/5]" first email?

From: Philip Oakley <philipoakley@iee.org>
Date: Sep 17, 2012, 22:55 UTC
Message-ID: <98180D4AA94C468887029389CC535D4F@PhilipOakley>
In-Reply-To: <7vzk4rz00y.fsf@alter.siamese.dyndns.org>

From: "Junio C Hamano" <gitster@pobox.com>

Show 21 quoted lines

> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> "Typically it will be placed in a MUA’s drafts folder, edited to add
>> timely commentary that should not go in the changelog after the three
>> dashes, and then sent as a message whose body, in our example, starts
>> with "arch/arm config files were…". On the receiving end, readers 
>> can
>> save interesting patches in a UNIX mailbox and apply them with
>> git-am(1)."
>>
>> hides a multitude of implicit knowledge steps. Is there an extended
>> description of what that would mean from a platform independent
>> viewpoint? e.g. if the patches are separte files and an mbox is one
>> consolidated file, how to get from one to the other so that 'it' can 
>> be
>> sent by 'git send-mail'.
>
> If you plan to use "git send-email" to send the final results out,
> you should consider "git send-email" as your "MUA" in the quoted
> paragraph.  And that will be very platform independent viewpoint to
> see things from.

On git for windows (msysgit)n there were a couple of other steps I had to do https://git.wiki.kernel.org/index.php/MSysGit:UsingSendEmail as Outlooklook Express isn't really a suitable MUA ;-) [noted for other list readers]

Show 7 quoted lines

>
> "git format-patch -o my-series/ --cover-letter ..."  would treat
> "my-series/" directory as "MUA's drafts folder" and prepares the
> messages you would want to send out, and you can proof-read and edit
> the files in there before telling your "MUA" to send them out, with
> "git send-email ... my-series/*.patch" or something.
>

I hadn't picked up from the man page that the --cover-letter would do the [PATCH 0/n] - should it?

Show 9 quoted lines

>> I'm also missing an understanding of the preparation stage where one
>> tries to tidy up the various commit messages becaue they weren't
>> explicit, specfic nor concise enough,...
>
> Many people usually do "rebase -i" until perfection and then a
> single final invocation of "format-patch".  Of course, the "final"
> can and should further be proof-read and it is fine to do typofixes
> in the format-patch output files without going back to the commits
> before sending them out.

I did an initial rebase to correct a few obvious mistakes (e.g. an extra 
file that had crept in), but then, after some false starts, used
    git format-patch pu --stdout > fix_Docs.patch
to get a single file I could inspect and refine for both the commit 
messages and content.

I then applied it (using git am) to a temp branch to see what it produced, and could repeat the cycle until the patches looked right.

Show 6 quoted lines

>
>> ...so I suspect that there is an
>> implicit `git format-patch` <-> `git am` loop of sharpening the mbox
>> patches before submission to the list that I'm missing. Has this
>> described somewhere?
> --

However, when it came to creating the series, with comments, I couldn't see a way of having my comments within my local commits, but preparing a patch series that would properly include the '---' separator.

Is there a way of getting format-patch to change some line break sequence (within the commit message) to the '---' three dashes patch break suitable for submission to the list?

Philip