https://github.com/mattduck/gh2md

Export Github repository issues, pull requests and comments to markdown.
https://github.com/mattduck/gh2md

github github-export github-issues github-issues-export github-markdown

Last synced: 3 months ago
JSON representation

Export Github repository issues, pull requests and comments to markdown.

• Host: GitHub
• URL: https://github.com/mattduck/gh2md
• Owner: mattduck
• License: mit
• Created: 2017-05-20T18:08:03.000Z (over 7 years ago)
• Default Branch: master
• Last Pushed: 2024-08-04T00:46:15.000Z (3 months ago)
• Last Synced: 2024-08-04T02:52:20.151Z (3 months ago)
• Topics: github, github-export, github-issues, github-issues-export, github-markdown
• Language: Python
• Homepage:
• Size: 990 KB
• Stars: 239
• Watchers: 7
• Forks: 44
• Open Issues: 10
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        
gh2md

=====

|PyPI|

Export issues and pull requests for a Github repository to a readable markdown

file. You can either create a single file for the repo, or a directory with one

file per issue. See usage instructions for how to filter by issue type and state.

There are various other projects that handle Github issue exports

(Eg. `offline-issues `_), but I

couldn't find one that writes all issues, comments and metadata to a single

readable file.

Example exports

---------------

- Basic export in `examples directory `_.

- `example directory with one issue per file `_

- gh2md's `own issues in a single file <./issues.md>`_.

Default behaviour is to export all issues and PRs.

Usage

-----

Run export for ``paulirish/git-open``, pulling token from environment, and excluding closed PRs:::

    export GITHUB_ACCESS_TOKEN=myAPItoken

    gh2md paulirish/git-open git-open.md --no-closed-prs

Run export for ``shezadkhan137/required``, pulling token from file, and excluding closed issues:::

    echo myAPItoken > ~/.config/gh2md/token

    gh2md shezadkhan137/required required.md --no-closed-issues

Run export for public repository ``sarabander/sicp``, using no authentication and one file per issue:::

    gh2md sarabander/sicp sicp-issues --multiple-files --no-closed-prs

Full help::

    usage: gh2md [-h] [--multiple-files] [-I] [--no-prs] [--no-closed-prs]

                [--no-issues] [--no-closed-issues]

                [--file-extension FILE_EXTENSION]

                repo output_path

    Export Github repository issues, pull requests and comments to markdown files:

    https://github.com/mattduck/gh2md

    Example: gh2md mattduck/gh2md my_issues.md

    Credentials are resolved in the following order:

    - A `GITHUB_ACCESS_TOKEN` environment variable.

    - An API token stored in ~/.config/gh2md/token or ~/.github-token.

    To access private repositories, you'll need a token with the full "repo" oauth

    scope.

    By default, all issues and pull requests will be fetched. You can disable these

    using the --no... flags, eg. --no-closed-prs, or --no-prs.

    positional arguments:

    repo                  Github repo to export, in format "owner/repo_name".

    output_path           Path to write exported issues.

    optional arguments:

    -h, --help            show this help message and exit

    --multiple-files      Instead of one file, treat the given path as a

                            directory, and create one file per issue, using a

                            format '{created_at}.{issue_number}.{issue_type}.{issu

                            e_state}{file_extension}'.

    -I, --idempotent      Remove non-deterministic values like timestamps. Two

                            runs of gh2md will always produce the same result, as

                            long as the Github data has not changed.

    --no-prs              Don't include pull requests in the export.

    --no-closed-prs       Don't include closed pull requests in the export.

    --no-issues           Don't include issues in the export.

    --no-closed-issues    Don't include closed issues in the export.

    --file-extension FILE_EXTENSION

                            File extension for output files. Default is '.md'.

Install

-------

``pip install gh2md``. Alternatively, clone the repository and run ``make install``.

Authentication

---------------

``gh2md`` requires a Github access token to authenticate requests. To read your

private repositories, you'll need to provide a personal access token with the

full **repo** oauth scope.

**It's not possible to authenticate with a username and password**. Github used

to support this, but it was discontinued in 2020.

Github workflow: backup issues as a markdown file in your repo

--------------------------------------------------------------

`@0ut0fcontrol `_ contributed a github workflow

that uses ``gh2md`` to run a nightly export to ``issues.md``, and push it back to

your repo. You can find the thread and workflow code `here

`_.

This has been added to the ``gh2md`` repo itself, so you can see an up-to-date

export in `issues.md <./issues.md>`_.

.. |PyPI| image:: https://img.shields.io/pypi/v/gh2md.svg

   :target: https://pypi.python.org/pypi/gh2md