GetGist

Easily download any file from a GitHub Gist, with one single command.

Why?

Because of reasons I do not have a dotfiles repository. I prefer to store my init.vim, .gitconfig, .bashrc etc. as Gists.

I wrote this CLI so I could update my dotfiles with one single command: getmy vim.init, for example — and it's done.

Install

$ pip install getgist

GetGist works with Python 3.6+.

To update it just run $ pip install --upgrade getgist.

Usage

Getting Gists from GitHub

Just run getgist <username> <filename>. For example:

$ getgist cuducos .vimrc
  Fetching https://api.github.com/users/cuducos/gists
  Reading https://gist.githubusercontent.com/cuducos/409fac6ac23bf515f495/raw/666d7d01a0058e4fd898ff752db66160f10a60bb/.vimrc
  Saving .vimrc
  Done!

GetGist asks you what to do when a local file (with the same name) exists. If you decide not to delete your local copy of the file, it will be renamed with extensions such as .bkp, .bkp1, .bkp2 etc.

Updating Gists at GitHub

Just run putgist <username> <filename> to update the remote Gist with the contents of the local file. It requires an OAuth token (see Using OAuth authentication below). For example:

$ putgist cuducos .vimrc
  User cuducos authenticated
  Fetching https://api.github.com/gists
  Sending contents of .vimrc to https://api.github.com/gists/409fac6ac23bf515f495
  Done!
  The URL to this Gist is: https://gist.github.com/cuducos/409fac6ac23bf515f495

GetGist asks you what to do when it finds the different files with the same name in different Gists.

Listing Gist files from GitHub

Just run lsgists <username>. For example:

$ lsgists cuducos
  Gist           File               URL
  -------------  ------------------ -------------------------
  First Gist     file.md            https://gist.github.com/…
  My Gist #2     another_file.md    https://gist.github.com/…
  My Gist #2     README.md          https://gist.github.com/…

Secret Gists (when user is authenticated) are listed with [Secret Gist] tag next to their names.

Using OAuth authentication

Why?

Add your personal access token as as environment variable to allow:

1. downloading private gists
2. updating existing gists
3. listing private gists

How?

1. Get a personal access token with permission to manage your gists from GitHub settings
2. Set an environment variable called GETGIST_TOKEN with your personal access token

This article might help you create an environment variable in a Unix-based operational system with Bash, but feel free to search alternatives for other systems and shells.

Example

$ export GETGIST_TOKEN=whatever1234
$ getgist cuducos .vimrc
  User cuducos authenticated
  Fetching https://api.github.com/gists
  Reading https://gist.githubusercontent.com/cuducos/409fac6ac23bf515f495/raw/666d7d01a0058e4fd898ff752db66160f10a60bb/.vimrc
  Saving .vimrc
  Done!
  The URL to this Gist is: https://gist.github.com/cuducos/409fac6ac23bf515f495

This will work even if the file you are trying to download is a private gist (surely the user name has to match the GETGIST_TOKEN account).

Setting a default user

Why?

Set a default user to avoid typing your GitHub user name all the time.

How?

1. Set an environment variable called GETGIST_USER with your GitHub user name
2. Use the shortcut getmy <filename>, putmy <filename> or mygists

Example

$ export GETGIST_USER=cuducos
$ getmy .vimrc
  Fetching https://api.github.com/users/cuducos/gists
  Reading https://gist.githubusercontent.com/cuducos/409fac6ac23bf515f495/raw/666d7d01a0058e4fd898ff752db66160f10a60bb/.vimrc
  Saving .vimrc
  Done!
  The URL to this Gist is: https://gist.github.com/cuducos/409fac6ac23bf515f495

Contributing

We use Poetry to manage our development environment:

1. poetry install will get you a virtualenv with all the dependencies for you
2. poetry shell will activate this virtualenv
3. exit deactivates this virtualenv

Feel free to report an issue, open a pull request, or drop a line.

Don't forget to format your code with Black, and to write and run tests:

$ tox