↓Skip to main content
IT Blog IT Blog
  1. All Posts/

gister

Tools Shell

gister

gister is a command line tool for managing GitHub gists.
Based on gist.rb by @defunkt, this tool helps you to manage a local copy of your gists.
After publishing files to gist.github.com, this tool will:

  • automatically clone the gist repository to local
  • index the content of your gist for code search
  • fetch meta info (e.g. description, url) of the gist from GitHub and add them to gists.list.

You can also use gister to sync your gists (created and starred)
between gist.github.com and your machine.

Dependencies

  • curl
  • git
  • gist.rb
  • jq

For Linux, BSD, etc, you also need xclip or xsel.
For Cygwin, you need putclip/getclip provided by cygutils-extra.
(Mas OS X users should be fine with the preinstalled pbcopy/pbpaste.)
Mac OS X users also need GNU versions of sed and date, a.k.a gsed and
gdate.
Note: xsel users should use gist.rb v4.1.2+, since there is a bug bitting xsel users in previous versions.

Optional Dependencies

  • csearch
    To search gists on your local machine.
    If not available, fallbacks to grep.
  • legit
    If available, invokes legit sync to sync gist repository.
    Legit will stash, fetch, rebase/merge, push, and unstash if necessary.
    The develop branch of legit allows configuration for merge policy:

      * The default smart merge (rebase when suitable)
  * Always merge, never rebase (since [21bb7ed])
  * Always rebase, never merge (since [252b1eb])
  * Fast forward merge only (since [4782928])

    <p>
  If legit is not available,<br /> gister will report dirty gist repositories (<code>DIRTY $gist_id</code>)<br /> when the environment variable <code>GISTER_AUTO_COMMIT</code> does not exist,<br /> and will commit files automatically when <code>GISTER_AUTO_COMMIT</code> exists. </li> </ul> 
  
  <h2 dir="auto">
    <a rel="nofollow noopener" target="_blank" id="user-content-install" class="anchor" aria-hidden="true" href="#install"></a>Install
  </h2>
  
  <p>
    Note that the following instructions only install gister itself.<br /> You need to install its dependencies mentioned before yourself.
  </p>
  
  <pre class="notranslate"><code>git clone https://github.com/weakish/gister.git

    cd gister make install 

      <ul dir="auto">
    <li>
      Edit <code>config.mk</code> if you do not want to install it to <code>/usr/local</code>.
    </li>
    <li>
      Compatible with both GNU and BSD make.
    </li>
  </ul>
  
  <p>
    To uninstall:
  </p>
  
  <pre>; cd gister

    ; make uninstall

      <p>
    You can also install/uninstall gister via basher.
  </p>
  
  <h2 dir="auto">
    <a rel="nofollow noopener" target="_blank" id="user-content-usage" class="anchor" aria-hidden="true" href="#usage"></a>Usage
  </h2>
  
  <h3 dir="auto">
    <a rel="nofollow noopener" target="_blank" id="user-content-init" class="anchor" aria-hidden="true" href="#init"></a>init
  </h3>
  
  <p>
    For the first time, you need to run <code>gister init</code> to associate your GitHub account and configure the directory to store local copies of your gists.<br /> After that, you may run <code>gister sync</code> to fetch all your gists (created and starred) to local.<br /> Warn: <code>sync</code> can only fetch up to 10 million gists for you. If you have more than 10 million gists, you need to modify the source of <code>gister</code> to lift the limit.
  </p>
  
  <h3 dir="auto">
    <a rel="nofollow noopener" target="_blank" id="user-content-configuration" class="anchor" aria-hidden="true" href="#configuration"></a>Configuration
  </h3>
  
  <p>
    <code>GISTER_USE_HTTPS</code>: If you need to use https for some reason, set the env var <code>GISTER_USE_HTTPS</code>, but please note this isn&#8217;t necessarily more secure than ssh, it&#8217;s just a different option in case your network blocks all traffic other than http/s.<br /> <code>GISTER_AUTO_COMMIT</code>: If you&#8217;d like the <code>sync</code> command to automatically commit any local changes you&#8217;ve made before pulling and pushing to gist.github.com, set the <code>GISTER_AUTO_COMMIT</code> env var to anything.
  </p>
  
  <h3 dir="auto">
    <a rel="nofollow noopener" target="_blank" id="user-content-publish" class="anchor" aria-hidden="true" href="#publish"></a>publish
  </h3>
  
  <p>
    Whenever you want to publish a gist, just use
  </p>
  
  <pre class="notranslate"><code>gister description file.txt ...


      <p>
    This will create the gist with the provided description, clone the gist repo, and put the gistid to clipborad.<br /> Note: you must provide gist description, otherwise <code>gister</code> will fail.<br /> Hint: <code>gister</code> will pass all arguments to gist as <code>gist -c -o -d description ...</code>, so you can use other options that gist understands, e.g. <code>gister description -P</code> will work.<br /> If you&#8217;ve edited your gists at <code>gist.github.com</code> or local machine, without pull/push changesets, you can sync all your gists via <code>gister sync</code>.<br /> If you&#8217;ve deleted your gists at <code>gist.github.com</code>, after <code>gister sync</code>, the directories of deleted gists at your local machine will be marked with a prefix <code>_</code>.
  </p>
  
  <h3 dir="auto">
    <a rel="nofollow noopener" target="_blank" id="user-content-search" class="anchor" aria-hidden="true" href="#search"></a>search
  </h3>
  
  <p>
    Search all of your gists:
  </p>
  
  <pre class="notranslate"><code>gister search regexp


      <p>
    If <code>codesearch</code> is installed, <code>regexp</code> is RE2 (nearly PCRE).<br /> Otherwise it is ERE, a.k.a <code>grep -E</code>.
  </p>
  
  <h3 dir="auto">
    <a rel="nofollow noopener" target="_blank" id="user-content-export" class="anchor" aria-hidden="true" href="#export"></a>export
  </h3>
  
  <p>
    Export a gist (available at local) to a git repository,<br /> with its full history:
  </p>
  
  <pre>; cd git-repo-root

    ; gister export gist_id sub_directory_name branch_name

      <p>
    The content of the gist will be exported to <code>sub_directory_name</code>,<br /> and the merging message will use <code>branch_name</code>.
  </p>
  
  <h3 dir="auto">
    <a rel="nofollow noopener" target="_blank" id="user-content-migrate" class="anchor" aria-hidden="true" href="#migrate"></a>migrate
  </h3>
  
  <p>
    From version 1.0.0, <code>gister</code> uses a different storage structure.<br /> If you have used <code>gister &lt;1.0.0</code>, then you need to run this command to migrate:
  </p>
  
  <pre class="notranslate"><code>gister migrate


      <h2 dir="auto">
    <a rel="nofollow noopener" target="_blank" id="user-content-storage" class="anchor" aria-hidden="true" href="#storage"></a>Storage
  </h2>
  
  <pre class="notranslate"><code>/path/to/your/gists

    |– gists.list # a list of all your gists (including meta info) |– repo # git repositories of your gists |– tree # working directory of your gist repositories |– 123456 # an example of gist |– _123567890 # an example of gist which you have deleted on gist.github.com |– … `– .csearchindex # code search index (optional) 

      <h2 dir="auto">
    <a rel="nofollow noopener" target="_blank" id="user-content-contributing" class="anchor" aria-hidden="true" href="#contributing"></a>Contributing
  </h2>
  
  <p>
    Send pull requests or issues at:<br /> https://github.com/weakish/gister
  </p>
  
  <h3 dir="auto">
    <a rel="nofollow noopener" target="_blank" id="user-content-tips" class="anchor" aria-hidden="true" href="#tips"></a>Tips
  </h3>
  
  <p>
    Setting environment variable <code>GISTER_DEBUG</code> to <code>true</code> (or any non-empty string) will enable debug mode (<code>set -x</code>).
  </p>


↑