aboutsummaryrefslogtreecommitdiffhomepage
path: root/README.md
diff options
context:
space:
mode:
authortypebrook <typebrook@gmail.com>2020-03-12 10:41:53 +0800
committertypebrook <typebrook@gmail.com>2020-03-12 10:41:53 +0800
commit50e624bb49c35e301a8afc466ab95df171a3b632 (patch)
tree70bda03635938a0779a53701ee0305387ff14bb3 /README.md
parent0fbccd2de45bad4bdf46326a0005c2fa563750df (diff)
update
Diffstat (limited to 'README.md')
-rw-r--r--README.md151
1 files changed, 151 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5b0a322
--- /dev/null
+++ b/README.md
@@ -0,0 +1,151 @@
1# gist - Manage you gist like a pro
2## Getting started
3```bash
4# fetch your gists and clone them into ~/gist as git repos
5gist fetch
6# show the list of your gists
7gist
8# create a new gist
9gist new
10# edit files in your third gist(default action), and get the path
11gist 3
12# push changes in your third gist to the remote repo
13gist push 3
14# update the description of your third gist
15gist edit 3
16# delete gists with index 3, 4 and 5
17gist delete 3 4 5
18# or use Brace Expansion
19gist delete {3..5}
20# Import your third gist as a new Github repo with web page
21gist github 3
22# For more detail, read the helper message
23gist help
24```
25## Commands
26### Update information and clone gists from Github
27Run `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`)
28- Automatically Clone/Pull each gist with git into a given folder. (default to `~/gist/`)
29- Run `gist fetch star` to fetch you starred gist
30- If token is not being set, then you cannot fetch your private gist
31
32### List your gists
33Run `gist` to read index file (default to `~/gist/index`) and list your gists with the folloing format:
34```
35[index] [gist-URL] [files-number] [comments-number] [description]
36```
37like following:
38![](https://i.imgur.com/CP6ZL2G.png)
39
40- Use `gist star` to show your starred gist
41- Index with prefix `s` is a starred gist, index with prefix `p` is a private gist
42- There are colorful hints for each gist in the following cases:
43 - **working:** some changes are made locally but not yet do `git commit`
44 - **ahead:** your local head is yet to be applied to upstream
45 - **outdated:** your local head is differs from the last fetched gists, do `gist fetch` to refresh index file and pull if needed
46
47### Create a new gist
48Run `gist new` to create a new gist
49- You can create a new gist with 3 different ways:
50 1. type the content by hand, run `gist new`
51 2. use existig files, run `gist new <file1> <file2>...`
52 3. from STDIN, like `<command> | gist new`
53- You can specify filename with `--file`, and description with `--desc`, like `gist new --file new --desc 'a new gist'`
54- If you don't specify filename or description, a prompt will shows up!
55
56### Modify a gist
57Run `gist <index-of-gist>` to use default editor to open files in local repo (by default action). Also use `cd $(gist <index-of-gist>)` to cd to that repo. You can do some trick to simplify it.(See [action](#action) and [Tips](#Tips))
58
59Since now a gist is a local cloned repo, it is your business to do git commit and git push. Use `gist push <index-of-gist>` is not recommended.
60
61### Clean unnecessary local repos
62Say 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`
63
64## Configuration
65`gist` stores your configuraion inside `~/.config/gist.conf`, with `<key>=<value>` 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).
66
67Valid keys are [`user`](#user), [`token`](#token), [`folder`](#folder), [`auto_sync`](#auto_sync), [`action`](#action) and [`EDITOR`](#EDITOR). Use the following commads to set value:
68``` bash
69gist config <key> <value>
70
71# Remove current value from a key
72gist config <key>
73
74# Or just modify ~/.config/gist.conf directly
75gist config
76```
77Each key is for the following use cases:
78
79### user
80Your Github username
81
82If 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).
83
84Use `gist config user <your-github-username>` to set the value if needed.
85
86### token
87Your Github API token for the given username. It's scope should be with `gist`.
88
89If 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.
90
91Use `gist config toekn <your-github-api-token>` to set the value if needed.
92
93### folder
94**[Optional]** The folder you stores index file and git repos for each your gists and starred gists. Default to `~/gist/` if not being set.
95
96Use `gist config folder <prefered-directory>` to set the value if needed.
97
98### auto_sync
99**[Optional]** Automatically clone/update your gists and starred gists as git repos when doing `gist fetch`. Default to be `true`.
100
101Use `gist config auto_sync false` to disable this feature.
102
103### action
104**[Optional]** A custom action is performed when you do `gist <index-of-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
105```
106${EDITOR:-vi} .
107```
108That is, use default editor or vi (if not set) to open the folder where the git repo of this gist is stored.
109
110For example, you can use the following command to change the action into "print the content of files and list filenames".
111```
112gist config action 'cat *; ls'
113```
114
115Also, if you run `gist <index-of-gist>` with `--no-action`, then action would not performs.
116
117### EDITOR
118**[Optional]** Editor to open `~/.config/gist.conf`. Default to be `vi` .
119
120For example, use `gist config EDITOR code` to use VSCode instead.
121
122### protocol
123**[Optional]** Protocol to clone git repo. Default to HTTPS
124valid values are:
125- https
126- ssh
127
128For example, use `gist config protocol ssh` to use SSH protocol instead.
129
130## Tips
131### Jump to gist repo
132Sometimes you want to switch to the specified gist repo as working directory.
133But 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.
134
135`gist <index-of-gist>` will return the path of repo, so you can put the following function into your `~/.bashrc` or `~/.zshrc` to apply it.
136```bash
137 function cdgist() {
138 local dir=$(gist $1 --no-action)
139 [[ -d $dir ]] && cd $dir
140 }
141 ```
142 And run `cdgist 3` to jump to the repo of your third gist.
143
144### Useful action for gist repo
145Though 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!
146
147If [`tig`](https://github.com/jonas/tig) is installed, run the following command to configure it as custom action:
148
149```
150gist config action 'tig -all'
151```