jayvdb / gists

Python CLI interface for managing gists

Gists

CLI interface for managing GitHub gists

Install it

Two ways of installation:

• Download the source code, extract it, and execute python setup.py install
• pip install gists

Configure it

First time you run 'gists', execute the command

$ gists authorize -u your_github_user

You will need to type your password, and The file ~/.gistsrc (which stores the 'gists' configuration) will be written with your GitHub api authentication token.

Anytime you can revoke your authentication token in your applications page on GitHub.

Use it!

List of Gists

Basic Usage

Return a list of gists. Basic usage is:

$ gists list

This will return a list of Gists from field user from credentials section in your (~/.gistsrc) file.

More arguments:

• -u (--user) specifies from whom user you want to retrieve his/her gists.
• -s (--starred) retrieves ONLY the starred gists.
• -p (--private) return the private gists besides the public ones.

Show a Gist

Shows the detail of a Gist. There are two modes here: without the -f argument, that will show the Gist metadata (url, description, name of the files...) and with the -f argument, that shows the content of one of the files of the Gist. Identifier of the Gist, (obtained via gists list) is mandatory as first argument.

Example without -f argument:

$ gists show e110cc498a31dc442fc3

Example with -f argument:

$ gists show e110cc498a31dc442fc3 -f examplegist.txt

Download a Gist

Download a file from a Gist using the 'get' action. While in the 'show' action the parameter -f is optional depending on the kind of data you want to show, here is mandatory. So, a basic usage is:

$ gists get e110cc498a31dc442fc3 -f examplegist.txt

The name of the target file in your local will be the same of the argument provided by -f. There is no way to change this. If the gist has only one file, the '-f-' parameter is not needed.

More arguments

• -o (--output_dir) destination directory where you want to save the gist

Create a Gist

Creates a Gist. Needs a file or a list of files to be uploaded. So, authentication and -f arguments are required. Basic usage is:

$ gists create -f examplegist.txt
$ gists create -f examplegist.txt examplegist2.txt

The name of the file in the OS will be the same of the name of the file in the Gist. No way to change this.

More arguments

• -u (--user) use this user instead of the one specified in configuration file. You will need to authenticate.
• -p (--private) whenever you want the Gist to be private.
• -d (--description) Set the description of the Gist.
• -i (--input_dir) Specify the input directory where the files are.

Update a Gist

Update an existent Gist. Several examples:

Modify just the description

To modify the description, use the -d (--description) argument:

$ gists update e110cc498a31dc442fc3 -d "New gist description"

Modify the contents of a file

Modify the contents of a File that already exists in the Gist:

$ gists update e110cc498a31dc442fc3 -f examplegist.txt

Add a new file to a Gist

Modify a Gist adding a new file, using the -n (--new) argument:

$ gists update e110cc498a31dc442fc3 -f new_file_to_gist.py -n

Remove a file from a Gist

Modify a Gist removing one of its files, using the -r (--remove) argument:

$ gists update e110cc498a31dc442fc3 -f no_longer_needed_file.py -r

Multiple files in the same gist

The past examples of the files update can be applied to serveral files, like creation command. In that case the parameters -i, -n and -r will be applied to all files from -f parameter:

$ gists update e110cc498a31dc442fc3 -f examplegist.txt examplegist2.txt
$ gists update e110cc498a31dc442fc3 -f new_file_to_gist.py new_file_to_gist2.py -n
$ gists update e110cc498a31dc442fc3 -f no_longer_needed_file.py no_longer_needed_file2.py -r
$ gists update e110cc498a31dc442fc3 -f new_file_to_gist.py new_file_to_gist2.py -n -i ../input_directory

More arguments

• -u (--user) use this user instead of the one specified in configuration file. You will need to authenticate.
• -i (--input_dir) Specify the input directory where the files are.

Fork a Gist

Basic Usage

Fork another user's gist and create a new one where you are the owner

$ gists fork gist_id

It will fork the gist. If the original gist is public, it will create a public gist. If it is private, it will create a private gist. There is no way to change that.

More arguments

• -u (--user) use this user instead of the one specified in configuration file. You will need to authenticate.

Star a Gist

Mark a Gist as starred.

Basic Usage

$ gists star gist_id

It will star the gist. It replicates the behavior of the Gists API. This is: sets the Gist as starred for the current user. If the Gist is already starred, a 'Success' will be returned. (It does not toggle star/unstar nor raises any 'Already Starred' exception)

More arguments

• -u (--user) use this user instead of the one specified in configuration file. You will need to authenticate.

Unstar a Gist

Mark a Gist as unstarred

Basic Usage

$ gists unstar gist_id

It will unstar the gist. It replicates the behavior of the Gists API. This is: sets the Gist as unstarred for the current user. If the Gist is already unstarred, a 'Success' will be returned. (It does not toggle star/unstar nor raises any 'Already Unstarred' exception)

More arguments

• -u (--user) use this user instead of the one specified in configuration file. You will need to authenticate.