hubmail

A tool to export GitHub issues and pull requests as email messages.

Differences from similar tools

The only similar tool of which I am aware is export-pull-requests by Skye Shaw, which exports only metadata and uses CSV format instead of email format.

Dependencies

Python 3.8, aiohttp, dateutil

Optional: mistletoe (for attaching linked images), argparse-manpage (for building a man page), POSIX shell (for running the testing script)

hubmail may also work on Python 3.7, but I have not tested it there.

If you use pip, you can run pip install -r requirements.txt to install all required and optional dependencies.

Usage

1. Create a peronal access token on GitHub's website following these instructions with the scopes public_repo, read:user, and user:email.
2. Set the environment variable HUBMAIL_TOKEN to your token.
3. Run python3 -m hubmail -h for usage information, and python3 -m hubmail SUBCOMMAND -h for usage information for a subcommand (e.g. issue, pull).

To install hubmail to your $PATH, run python3 setup.py install. This will also install man page documentation if you have argparse-manpage installed (run man 1 hubmail or man -l man/hubmail.1 to view it).

For example, to fetch the oldest 10 issues and the newest 5 pull requests from user/repo, wrapped to 72 characters and with the first 20 comments on each, output to the file repo.mbox:

$ hubmail issues -t10 -c20 -w72 user repo >  repo.mbox
$ hubmail pulls  -t-5 -c20 -w72 user repo >> repo.mbox

Testing

Create a file with contents like the following and put it at test/config:

#!/bin/sh

# Command line to run hubmail (`hubmail` should work if you have installed it
# into your $PATH)
hubmail='python3 -m hubmail'

dir=messages

# Send all messages to this file (leave blank to disable)
all=all.mbox

# Format of each line: ARGUMENTS:FILENAME
cmds="
issue -c -w --  myuser myrepo 1:file1.mbox
pull  -c20 -w72 myuser myrepo 2:file1.mbox
"

Then run ./test/test to run hubmail and output files to the chosen directory with the chosen filenames.

Features

• Outputs in the mbox format as specified in RFC 4155
• Can fetch one issue or pull request (by number), or many issues or pull requests in a repository, optionally with comments with support for forward and reverse pagination
• Pull requests are exported as both patches and discussions
• The Message-ID, In-Reply-To, and References headers are used to support conversation threading
• Optional text wrapping with quote recognition
• Supports comments authored by users, organizations, and bots
• Supports formatting subject line like GitHub notification emails
• Linked images are downloaded and added as attachments
• Supports compiling multipart emails with Markdown rendered to HTML

Roadmap

• Add support for changing message IDs to differ from the GitHub notification emails
• Include non-comment actions; e.g., pull request reviews and merges
• Keep track of rate limit and pause if it is reached
• Add support for keeping usernames instead of real names (or both?)
• More graceful error handling (e.g. when a repository is not found)

And possibly:

• Add support for edited issues
  • It may be useful just to act as if the issue was never edited, as Git does with commits

Bugs

asyncio throws exceptions on Windows about cancelling overlapping futures and the event loop being closed, but hubmail works fine otherwise on Windows (the exceptions can be ignored by redirecting stderr)

License

SPDX-License-Identifier: LGPL-2.1-or-later

hubmail: a tool to export GitHub issues and pull requests as email messages

Copyright (c) 2020 psvenk

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA