gist - Manage your gist like a pro

All your notes, scripts, config files and snippets deserve version control and tagging!
gist is a simple bash script for gist management. It is light and dependency-free! Helps you to boost coding workflow.

Getting Started

# Install with script on GitHub Page
curl -fsSL https://typebrook.github.io/gist/install.sh | bash
# Fetch your gists and clone them into ~/gist as git repos
gist fetch
# List your gists
gist
# Create a new gist
gist new
# Create private gist with files 'foo' and 'bar'
gist new -p foo bar
# Check information of your third gist
gist detail 3
# Get the path and cd to cloned repo with subshell
gist 3
# List your gists with tags instead of URL
gist tag
# Add tags to your third gist
gist tag 3
# Update the description of your third gist
gist edit 3
# Push changes in your third gist to the remote repo
gist push 3
# Delete gists with indices 3, 4 and 5
gist delete 3 4 5
# Or use Brace Expansion
gist delete {3..5}
# Export your third gist as a new Github repo with web page
gist github 3
# For more detail, read the helper message
gist help

Dependencies

OK...I lied, this script really depends on some very basic dev tools.

• GNU coreutils
  Used to process text streams. Also, if you are on Mac and use sed, tail with BSD version, then it is still fine!
• wget or curl
  Used to making request to github.com.
• git
  Do not tell me you don't have it on your machine...
• Python
  Both 2 and 3 works. It is used to process JSON response from github.com and launch default browser.(Only built-in modules are used)

Basic Commands

Update and clone gists from Github

Run gist fetch to fetch your all gists with Github API and keep short information for each gist in a index file inside a given folder. (default to ~/gist/index)

• Automatically Clone/Pull each gist with git into a given folder. (default to ~/gist/)
• Run gist fetch star to fetch your starred gist
• If token is not being set, then you cannot fetch your private gist

List your gists

Run gist to read index file (default to ~/gist/index) and list your gists with the following format:

<index> <gist-URL> <files-number> <comments-number> <description>

like the following:

• Use gist star to show your starred gists
• Use gist all to show your and starred gists
• Index with prefix s is a starred gist, index with prefix p is a private gist
• There are colorful hints for each gist in the following cases:
  • working Some changes are made locally but not yet do git commit, or you are not in master branch
  • ahead Your local HEAD is yet to be applied to upstream
  • outdated Your local HEAD is differs from the last fetched gists, do gist fetch to refresh index file and pull if needed

Create a new gist

Run gist new to create a new gist

• You can create a new gist with 3 different ways:
  1. type the content by hand, run gist new
  2. use existing files, run gist new <file1> <file2>...
  3. from STDIN, like <command> | gist new
• You can specify filename with --file, and description with --desc, like gist new --file new --desc 'a new gist'
• If you don't specify filename or description, a prompt will shows up!

Modify a gist

Run gist <INDEX> to enter sub-shell with working directory of the given gist index (by default action). You can do some trick with custom action.(See action and Tips)

Since now a gist is a local cloned repo, it is your business to do git commit and git push. Use gist push <INDEX> is not recommended.

Clean unnecessary local repos

Say you delete gists with command gist delete <index-of-gist>..., the local git repositories are still at ~/gist/.
Run gist clean to move them into /tmp/gist/.

Configuration

gist stores your configuraion inside ~/.config/gist.conf, with <key>=<value> format for each line. And just do source ~/.config/gist.conf at runtime.

~/.config/gist.conf is created automatically when you run gist at the first time, it only allows current user to read and write (permission 600).

Valid keys are user, token, folder, auto_sync, action, EDITOR, protocol and show_untagged. Use the following commands to set value:

# Set key with a given value
gist config <key> <value>

# Remove current value from a key
gist config <key>

# Or just modify ~/.config/gist.conf directly
gist config

Each key is for the following use cases:

Your Github username

If you use command which needs username and user is not being set, a prompt will shows up and requires your username and API token.

Use gist config user <your-github-username> to set the value if needed.

token

Your Github API token for the given username. It's scope should be with gist.

If you use command which needs it and it is not being set, A prompt will shows up and requires it. You can choose going to web page to create a new token, or just input an existing one directly.

Use gist config toekn <your-github-api-token> to set the value if needed.

folder

[Optional] The folder you stores index file and git repos for each your gists and starred gists. Default to ~/gist/ if not being set.

Use gist config folder <prefered-directory> to set the value if needed.

auto_sync

[Optional] Automatically clone/update your gists and starred gists as git repos when doing gist fetch. Default to be true.

Use gist config auto_sync false to disable this feature.

action

[Optional] A custom action is performed when you do gist <INDEX> (like gist 3 for your third gist). If is being set, gist will cd to the cloned repo, and just simply use eval to perform action.

For example, you can use the following command to print the filename and its content of all files inside the given gist

gist config action 'tail -n +1 *'

If action is not being set, then a default action will be performed:

# Enter sub-shell with current shell or bash
${SHELL:-bash}

Also, if you run gist <INDEX> with --no-action(or -n), then action would be ignored.

EDITOR

[Optional] Editor to open ~/.config/gist.conf. Default to be vi .

For example, use gist config EDITOR code to use VSCode instead.

protocol

[Optional] Protocol to clone git repo. Default to be HTTPS

Valid values are:

• https

For example, use gist config protocol ssh to use SSH protocol instead.

show_untagged

[Optional] Whether to show untagged gists when using gist tag. Default to be true

Use gist config show_untagged false to disable this feature.

Filter gists

Filter by tags

gist treats trailing hashtags inside gist description as tags. For example, if a description is:

[Title] this is description #tag1 #tag2

When gist is performed, it only display description with part: [Title] this is description, and treat the trailing hashtags as tags of a gist.

Tag a gist

You can use the following command to add/remove tags:

# tag your third gist
gist tag 3

After it is finished, gist just calls Github API to apply new description onto the given gist.

List gists with tags

Use sub-command tag to list gists with tags instead of URLs.

# show tags for your gists
gist tag

Filter gists with tags

If arguments after gist tag are not indices of gist, then they will be treated as tag values. The output will be a list of gists with those tags

# Filter gists with tag1 and tag2
gist tag tag1 tag2

You can also use regex pattern as tag value:

# only show tagged gists
gist tag .+

Show existing tags

Use sub-command tags to show existing tags and pinned tags. They are sorted alphabetically.

gist tags

Pin/Unpin tags

Say you are working with gists with some meaningful tags. You can use sub-command pin to pin them, and filter your gists with pinned tags

# Pin tag1 and tag2, If a tag is pinned, then unpin it
gist pin tag1 tag2
# Disply gists with pinned tags
gist pin

Filter by pattern

You can search gists with pattern in description, filename or file contents with sub-command grep

# search by a simple string
gist grep string
# search by a pattern(heading string in a line)
gist grep '^string'

Filter by file languages

List gists with languages

You can use sub-command lan to List gists with file languages instead of URLs.

# show languages for your gists
gist lan

Filter gists with languages

# Filter gists with files in Shell and Yaml format
gist lan LANGUAGE1 LANGUAGE2...

Index Range

You can specify the range of indices, works both on your owned gists and starred gists.

# only show gists with index 5 to 10
gist 5-10
# show gists from index 5
gist 5-
# show starred gists only to index s10
gist -s10
# only show gists with index 1 to 20
seq 20 | gist

Filter gists with pipe

If STDIN is from a pipe, then gist will only process gists with indices in the first column. So, you can concatenate the output of each sub-command.

# only show gists with index 1 to 20
seq 20 | gist
# List starred gist with Yaml file
gist star | gist lan Yaml
# Only List gists with tag1, pattern1 in description/filenames/contents and contains shell script
gist tag tag1 | gist grep pattern1 | gist lan SHELL

Git Workflow

Each gist is a git repository.
Although there are some limits on git push, like sub-directory is prohibited. But guess what?

1. Push another branch to github.com is allowed.
2. Push tags is also allowed. And like repos in github.com, you can get source file by reference with URL:

   https://codeload.github.com/gist/<gist_id>/tar.gz/<YOUR TAG or BRANCH>
   

Useful action for gist repo

I strongly recommend using tig as your custom action. It is the most powerful git CLI tool as far as I know, and also easy to get in most of the Linux distros or Homebrew for mac. Give it a try!

If tig is installed, run the following command to configure it as custom action:

gist config action 'tig -all'

tig interface for history diagram:

Suppress action

If action is not being set, you will enter sub-shell by default. If you want suppress it and do not want to type --no-action every time, just use command ture to do nothing.

gist config action 'true'

Suppress hint

There are several environment variables or arguments can suppress hint or user confirm, like:

# List gists without hint
hint=false gist

# Just print the repo path with a given index
gist 3 --no-action
# Or shorter argument
gist 3 -n

# Delete your third gist without confirmation
gist delete 3 --force