gister
======

`gister` is a command line tool for managing GitHub gists.

Based on [gist.rb][gist] by [@defunkt][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`.

[gist]: https://github.com/defunkt/gist
[defunkt]: https://github.com/defunkt

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

Dependencies
------------

- curl
- git
- [gist.rb][gist]
- [jq](http://stedolan.github.io/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][151].

[151]: https://github.com/defunkt/gist/pull/151

### Optional Dependencies

- [csearch](https://github.com/google/codesearch)

    To search gists on your local machine.
    If not available, fallbacks to `grep`.

- [legit](https://github.com/kennethreitz/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])

    If legit is not available,
    gister will report dirty gist repositories (`DIRTY $gist_id`)
    when the environment variable `GISTER_AUTO_COMMIT` does not exist,
    and will commit files automatically when `GISTER_AUTO_COMMIT` exists.

[21bb7ed]: https://github.com/kennethreitz/legit/commit/21bb7edd081f9e47abec9b970b32f2814104d298
[252b1eb]: https://github.com/kennethreitz/legit/commit/252b1eb2cd1c0a8f223fa8022ed37752bd5d6cec
[4782928]: https://github.com/kennethreitz/legit/commit/478292899831c1da478490970bc5d4f66d117510

Install
-------

Note that the following instructions only install gister itself.
You need to install its dependencies mentioned before yourself.

    git clone https://github.com/weakish/gister.git
    cd gister
    make install

By default gister will be installed into `/usr/local/bin/gister`.
Change `PREFIX` to install r3c to another directory.
For example:

```sh
make PREFIX=~/.local install
```

The Makefile is compatible with both GNU and BSD make.

To uninstall:

```sh
; cd gister
; make uninstall
```

If you have changed the `PREFIX` variable when installing, you need to use the same value when uninstalling.
For example:

```sh
make PREFIX=~/.local uninstall
```

You can also install/uninstall gister via [basher].

[basher]: https://github.com/basherpm/basher

Usage
-----

### init

For the first time, you need to run `gister init` to associate your GitHub account and configure the directory to store local copies of your gists.

After that, you may run `gister sync` to fetch all your gists (created and starred) to local.

Warn: `sync` 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 `gister` to lift the limit.

### Configuration

`GISTER_USE_HTTPS`: If you need to use https for some reason, set the env var `GISTER_USE_HTTPS`, but please note this isn't necessarily more secure than ssh, it's just a different option in case your network blocks all traffic other than http/s.

`GISTER_AUTO_COMMIT`: If you'd like the `sync` command to automatically commit any local changes you've made before pulling and pushing to gist.github.com, set the `GISTER_AUTO_COMMIT` env var to anything.

### publish

Whenever you want to publish a gist, just use

    gister description file.txt ...

This will create the gist with the provided description, clone the gist repo, and put the gistid to clipborad.

Note: you must provide gist description, otherwise `gister` will fail.

Hint: `gister` will pass all arguments to gist as `gist -c -o -d description ...`, so you can use other options that gist understands, e.g. `gister description -P` will work.

If you've edited your gists at `gist.github.com` or local machine, without pull/push changesets, you can sync all your gists via `gister sync`.

If you've deleted your gists at `gist.github.com`, after `gister sync`, the directories of deleted gists at your local machine will be marked with a prefix `_`.

### search

Search all of your gists:

    gister search regexp

If `codesearch` is installed, `regexp` is RE2 (nearly PCRE).
Otherwise it is ERE, a.k.a `grep -E`.

### export

Export a gist (available at local) to a git repository,
with its full history:

```sh
; cd git-repo-root
; gister export gist_id sub_directory_name branch_name
```

The content of the gist will be exported to `sub_directory_name`,
and the merging message will use `branch_name`.

### migrate

From version 1.0.0, `gister` uses a different storage structure.
If you have used `gister <1.0.0`, then you need to run this command to migrate:

    gister migrate


Storage
-------

    /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)


Contributing
------------

Send pull requests or issues at:

https://github.com/weakish/gister

### Tips

Setting environment variable `GISTER_DEBUG` to `true` (or any non-empty string) will enable debug mode (`set -x`).