From 50e624bb49c35e301a8afc466ab95df171a3b632 Mon Sep 17 00:00:00 2001 From: typebrook Date: Thu, 12 Mar 2020 10:41:53 +0800 Subject: update --- README.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..5b0a322 --- /dev/null +++ b/README.md @@ -0,0 +1,151 @@ +# gist - Manage you gist like a pro +## Getting started +```bash +# fetch your gists and clone them into ~/gist as git repos +gist fetch +# show the list of your gists +gist +# create a new gist +gist new +# edit files in your third gist(default action), and get the path +gist 3 +# push changes in your third gist to the remote repo +gist push 3 +# update the description of your third gist +gist edit 3 +# delete gists with index 3, 4 and 5 +gist delete 3 4 5 +# or use Brace Expansion +gist delete {3..5} +# Import your third gist as a new Github repo with web page +gist github 3 +# For more detail, read the helper message +gist help +``` +## Commands +### Update information 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 you 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 folloing format: +``` +[index] [gist-URL] [files-number] [comments-number] [description] +``` +like following: +![](https://i.imgur.com/CP6ZL2G.png) + +- Use `gist star` to show your starred gist +- 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` + - **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 existig files, run `gist new ...` + 3. from STDIN, like ` | 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 ` to use default editor to open files in local repo (by default action). Also use `cd $(gist )` to cd to that repo. You can do some trick to simplify it.(See [action](#action) and [Tips](#Tips)) + +Since now a gist is a local cloned repo, it is your business to do git commit and git push. Use `gist push ` is not recommended. + +### Clean unnecessary local repos +Say you delete gists with command `gist delete ...`, the local git repositories are still at `~/gist/`. Run `gist clean` to move them into `/tmp` + +## Configuration +`gist` stores your configuraion inside `~/.config/gist.conf`, with `=` format for each line. And just do `source ~/.config/gist.con` at runtime. This file is created automatically when you do the first configuration, and only allows current user to read and write (permission 600). + +Valid keys are [`user`](#user), [`token`](#token), [`folder`](#folder), [`auto_sync`](#auto_sync), [`action`](#action) and [`EDITOR`](#EDITOR). Use the following commads to set value: +``` bash +gist config + +# Remove current value from a key +gist config + +# Or just modify ~/.config/gist.conf directly +gist config +``` +Each key is for the following use cases: + +### user +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`](#token). + +Use `gist config user ` 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 ` 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 ` 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 ` (like `gist 3` for your third gist). If is being set, `gist` will automatically cd to the folder of gist repo, and just simply use `eval` to perform action. Default to be +``` +${EDITOR:-vi} . +``` +That is, use default editor or vi (if not set) to open the folder where the git repo of this gist is stored. + +For example, you can use the following command to change the action into "print the content of files and list filenames". +``` +gist config action 'cat *; ls' +``` + +Also, if you run `gist ` with `--no-action`, then action would not performs. + +### 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 HTTPS +valid values are: +- https +- ssh + +For example, use `gist config protocol ssh` to use SSH protocol instead. + +## Tips +### Jump to gist repo +Sometimes you want to switch to the specified gist repo as working directory. +But since `gist` is a bash script which goes in subshell, if you want to achieve this, it is necessary to configure shell setting by yourself. + +`gist ` will return the path of repo, so you can put the following function into your `~/.bashrc` or `~/.zshrc` to apply it. +```bash + function cdgist() { + local dir=$(gist $1 --no-action) + [[ -d $dir ]] && cd $dir + } + ``` + And run `cdgist 3` to jump to the repo of your third gist. + +### Useful action for gist repo +Though default [`action`](#action) is to open gist repo in vi, I strongly recommend use [`tig`](https://github.com/jonas/tig) instead. It is the most powerful git CLI tool as far as I know, and also easy to get in most of the Linux distros and Homebrew for mac. Give it a try! + +If [`tig`](https://github.com/jonas/tig) is installed, run the following command to configure it as custom action: + +``` +gist config action 'tig -all' +``` -- cgit v1.2.3-70-g09d2