zunzuncito

Even though git-send-email(1) calls git-format-patch(1) if you provide a revision list, oftentimes when submitting a patch series you should instead run git-format-patch(1) first, and later use git-send-email(1) only to submit the files it generated. There’s a bunch of reasons for this.

1. send-email is built chiefly for mail submission, not patch formatting. There is no way to pass options meant for format-patch, meaning that you miss out on really good features like --cover-letter or --interdiff.

2. If you use --annotate or decide to edit the mail body, you will lose all changes if you quit before sending. You can’t save your work and continue writing the mail later either. Once you call send-email, you’re committed; It’s all or nothing.

3. --compose gets you a worse version of format-patch’s --cover-letter. No diffstat is included by default, and the same problems as in 2) apply.

4. format-patch outputs text files for you to browse and edit. This can be done on your own time and with your own tools, without the send-email prompt nagging and stressing you.

Providing a convenient way of quickly sending out small patches makes sense, but all in all I think the inclusion of formatting in git-send-email(1) is a glaring misfeature. Hiding git-format-patch(1) away from the user makes git-send-email(1) intransparent and, worse, really clunky to use for regular patch workflows.

Sadly, git-send-email.io still tells newcomers to use only get-send-email(1), without even mentioning git-format-patch(1). This won’t change any time soon, either.

That is a shame. Guiding people to a worse workflow will not increase the standing of mail-based processes. For now I’d recommend linking newcomers this section of Git’s own contribution tutorial instead.