From 84d36e036b9b7981b10d173c682d1160cd99028f Mon Sep 17 00:00:00 2001 From: Drew DeVault Date: Thu, 4 Apr 2019 12:33:18 -0400 Subject: Update send-email guide --- git.sr.ht/send-email.md | 281 +----------------------------------------------- 1 file changed, 3 insertions(+), 278 deletions(-) diff --git a/git.sr.ht/send-email.md b/git.sr.ht/send-email.md index 6a1954f..907f082 100644 --- a/git.sr.ht/send-email.md +++ b/git.sr.ht/send-email.md @@ -1,282 +1,7 @@ -sr.ht leverages git's built-in collaboration tools for contributing to projects -hosted here. This guide will help you get started. If you run into any trouble, -please send an email to the [sr.ht-discuss][sr.ht-discuss] mailing list for -help. +This horrible wall of text has been replaced with a much better interactive +tutorial on using git send-email to send patches by email. Check it out here! -[sr.ht-discuss]: https://lists.sr.ht/~sircmpwn/sr.ht-discuss - -**Golden rule**: Do not copy-paste the output of git format-patch into your -typical mail client. - -# For everyone - -Before you dig too far into this guide, you should make sure that your email -client is configured to use plain text emails. By default, many email clients -compose emails with HTML, so you can use rich text formatting. Rich text is not -desirable for development-oriented email conversations, so you should disable -this feature and send your email as "plain text". Every email client is -different, you should research the options for your specific client. HTML emails -are rejected by all sr.ht services. - -For real-world examples of how the discussions described in this document play -out, check out the [sr.ht-dev][sr.ht-dev] mailing list. - -[sr.ht-dev]: https://lists.sr.ht/~sircmpwn/sr.ht-dev - -Unsure if your setup is correct? Try sending the patch to sir@cmpwn.com for -feedback first - make sure you mention in the email that you want feedback. - -# For contributors - -## Preparing your changes - -There's no need to "fork" the repository you want to contribute to - simply use -[`git clone`][git-clone] to obtain a local copy of the git repository and [work -normally][work-normally]. Be deliberate about your commits - use meaningful -commit messages and take special care to commit your work in the form of -logically separate changes. When it comes time to review your work, your commit -history is an important tool for the reviewer and will be closely examined. - -[git-clone]: https://www.git-scm.com/docs/git-clone -[work-normally]: https://www.git-scm.com/book/en/v2 - -## Find out where to send your changes - -This workflow is optional for projects hosted on sr.ht and each project will -have different requirements - review them carefully. To use this guide, you need -to find an email address to send your work to - this will often be a mailing -list on [lists.sr.ht](/lists.sr.ht). You will also want to find people who can -help review your changes - look for dedicated maintainers for the modules you're -working on, or use [`git blame`][git-blame] to find people who have recently -worked on similar code. - -[git-blame]: https://www.git-scm.com/docs/git-blame - -## Installation of git send-email - -The Git project includes `send-email`, unfortunately, not all installations of -Git will include `send-email` by default. If you find it is missing from your -system, try installing the relevant package from the table below: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
OS/PackagerPackage Name
Alpinegit-email
CentOSgit-email
Debiangit-email
Fedoragit-email
FreeBSD Portsgit
Homebrewgit
nixpkgsgitFull
openSUSEgit-email
pkgsrcgit
Ubuntugit-email
WindowsIncluded in download from git-scm.com
- -## Configure git send-email - -When you've collected a list of email addresses to send your work to, we can use -[`git send-email`][git-send-email] to do the job. Its purpose is to convert your -git commits into emails with [`git format-patch`][git-format-patch] and connect -to your mail server to deliver them with SMTP. - -[git-send-email]: https://www.git-scm.com/docs/git-send-email -[git-format-patch]: https://www.git-scm.com/docs/git-send-email - -If you've never used git send-email before, you will need to do some one-time -setup to introduce it to your SMTP server. The connection details vary between -mail providers, but you're looking for information which is suitable for filling -out these config fields in `~/.config/git/config`: - - [sendemail] - smtpencryption = tls - smtpserver = mail.example.org - smtpuser = you@example.org - smtpserverport = 587 - -**Note**: G-Mail users have to take some extra steps, which are documented -[here][gmail]. - -[gmail]: https://www.git-scm.com/docs/git-send-email#_use_gmail_as_the_smtp_server - -**Note**: Protonmail users are advised to use -[Hydroxide](https://github.com/emersion/hydroxide) to extend Protonmail with -SMTP support, and to choose mail services which support standard, open protocols -in the future. - -You can also set your SMTP password as `sendemail.smtppass`. If you don't, you -will be prompted for it when it's needed. You can also configure git to use your -local keyring; consult [`git credential`][git-credential] for details. - -[git-credential]: https://www.git-scm.com/docs/git-credential - -## Send the patches along - -When you've configured `git send-email`, completed your work, and you're ready -to send your patches in, you can run `git send-email --annotate [rev-spec...]`. -The `rev-spec` is the same as any other [revision specification][rev-spec], and -send-email will prepare patches from that commit to the tip (unless you specify -`-1`, `-2`, etc, in which case it will prepare up to that many patches). If -you're in a hurry, here are a few quick examples: - -- `HEAD^` just includes the last commit -- `HEAD~3` includes the last three commits -- `origin/master` includes all commits since diverging from `origin/master` -- `0fdbc0da` only includes commit `0fdbc0da` when specified with `-1` -- `0fdbc0da` includes commit `0fdbc0da` and the 2 commits prior when specified - with `-3` - -[rev-spec]: https://www.git-scm.com/docs/gitrevisions - -The `--annotate` flag will open the emails in your text editor before sending -them out. You should take a moment to review these. The subject line and -everything above the `---` are your commit message, and everything below the -`---` is the patch itself. Immediately following the `---`, you can add what -we call "timely commentary" - any information which is useful to the people -reviewing your patch, but doesn't necessarily belong in the final git history; -plus a blank line between this and the start of the patch. If you're sending a -few patches at once, you might also want to specify `--cover-letter`, which will -prepare an additional email summary to be sent first. - -**Note**: When you're prompted for an "In-Reply-To" header, you can ignore it -for now. - -## Using request-pull - -For integrating large changesets, merging unrelated branches, or for maintainers -who prefer this workflow, you may want to use a "pull request". To use this -workflow you will need to have somewhere public to host your modified copy of -the git repository, like git.sr.ht. If you already have the upstream repository -cloned locally, take these steps to push your changes to your own git.sr.ht -repository: - - git remote rename origin upstream - git remote add origin git@git.sr.ht:~yourname/some-project - git push -u origin master - -Click the link to confirm the creation of your repository. Take care to update -the URL provided to `git remote`. Then generate the pull request: - - git request-pull -p [rev-spec...] origin - -You can copy-paste the output into your email client (remember to ensure you are -not sending HTML email) and add any timely commentary in front. - -## Handling feedback - -You will likely receive replies to your email with feedback on your changes. -This is normal! Use tools like [`git commit --amend`][amend] and [`git -rebase`][git-rebase] to continue improving your patch set and iterating on -feedback (tip: check out our [rebase guide](rebase.md)). When you're ready to -submit the next version of your patches, use `git send-email` normally, except: - -- Add `-v2` to indicate that this is version 2 of your patch (or whatever number - is appropriate). -- When prompted to fill out `In-Reply-To`, paste in the message ID of the last - email in the thread. On lists.sr.ht you can get this by clicking "details" on - the email in question. If you can't find this, don't sweat it, it's no big - deal. - -**Note**: you can also specify the In-Reply-To with the `--in-reply-to` command -line argument. - -[amend]: https://www.git-scm.com/docs/git-commit#git-commit---amend -[git-rebase]: https://www.git-scm.com/docs/git-rebase - -## Pulling from upstream - -As you continue to work, you may want to pull from the upstream, and you -almost certainly don't want to create a merge commit when you have WIP or -unmerged patches in your history. To this end, you should generally use `git -pull --rebase` to fetch the latest changes from upstream. - -If you get a conflict, read the information git prints. You have two choices - -skip the patch or fix it. If your patch has already been merged, the maintainer -likely made some minor changes that prevents git from detecting it's the same -commit you have locally - in this case, just `git rebase --skip` the patch. If -your patch still hasn't been merged upstream, you should resolve the conflicts -in your editor, using `git add some/file.c` to mark the conflicts as resolved, -and then using `git rebase --continue` to move on. You will probably want to -send a `-v2` patch upstream when you're done - any conflicts you resolved, your -maintainer will have to address, too. Save them the time! - -## Extra tips - -Here are a few extra tricks you might find useful with `git send-email`. - -### Sending emails to the same address every time - -If you send emails for a project to the same mailing list every time, you might -find it useful to set the default To address. Run this command from that -repository: - - git config sendemail.to patches@example.org - -### Specifying a subproject for shared lists - -Some projects have several repositories being discussed on a single mailing -list, and it's often helpful to specify the particular repository your patch -pertains to. - -If you're just doing this once, add `--subject-prefix` to `git send-email`, like -so: - - git send-email --subject-prefix='PATCH example' HEAD^ - -You can also specify this as the default for that git repository: - - git config format.subjectPrefix 'PATCH example' - -### Signing off on your commits - -If you're asked by a project to "sign off" on your commits, add `--signoff` (or -`-s`) to `git send-email`. To set it as the default for that git repository: - - git config format.signOff yes - -### Using --annotate every time - - git config --global sendemail.annotate yes +https://git-send-email.io # For maintainers -- cgit