diff options
author | typebrook <typebrook@gmail.com> | 2020-03-12 10:41:53 +0800 |
---|---|---|
committer | typebrook <typebrook@gmail.com> | 2020-03-12 10:41:53 +0800 |
commit | 50e624bb49c35e301a8afc466ab95df171a3b632 (patch) | |
tree | 70bda03635938a0779a53701ee0305387ff14bb3 /README.md | |
parent | 0fbccd2de45bad4bdf46326a0005c2fa563750df (diff) |
update
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 151 |
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 | ||
5 | gist fetch | ||
6 | # show the list of your gists | ||
7 | gist | ||
8 | # create a new gist | ||
9 | gist new | ||
10 | # edit files in your third gist(default action), and get the path | ||
11 | gist 3 | ||
12 | # push changes in your third gist to the remote repo | ||
13 | gist push 3 | ||
14 | # update the description of your third gist | ||
15 | gist edit 3 | ||
16 | # delete gists with index 3, 4 and 5 | ||
17 | gist delete 3 4 5 | ||
18 | # or use Brace Expansion | ||
19 | gist delete {3..5} | ||
20 | # Import your third gist as a new Github repo with web page | ||
21 | gist github 3 | ||
22 | # For more detail, read the helper message | ||
23 | gist help | ||
24 | ``` | ||
25 | ## Commands | ||
26 | ### Update information and clone gists from Github | ||
27 | 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`) | ||
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 | ||
33 | Run `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 | ``` | ||
37 | like following: | ||
38 |  | ||
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 | ||
48 | Run `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 | ||
57 | Run `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 | |||
59 | Since 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 | ||
62 | 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` | ||
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 | |||
67 | 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: | ||
68 | ``` bash | ||
69 | gist config <key> <value> | ||
70 | |||
71 | # Remove current value from a key | ||
72 | gist config <key> | ||
73 | |||
74 | # Or just modify ~/.config/gist.conf directly | ||
75 | gist config | ||
76 | ``` | ||
77 | Each key is for the following use cases: | ||
78 | |||
79 | ### user | ||
80 | Your Github username | ||
81 | |||
82 | 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). | ||
83 | |||
84 | Use `gist config user <your-github-username>` to set the value if needed. | ||
85 | |||
86 | ### token | ||
87 | Your Github API token for the given username. It's scope should be with `gist`. | ||
88 | |||
89 | 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. | ||
90 | |||
91 | Use `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 | |||
96 | Use `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 | |||
101 | Use `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 | ``` | ||
108 | That is, use default editor or vi (if not set) to open the folder where the git repo of this gist is stored. | ||
109 | |||
110 | For example, you can use the following command to change the action into "print the content of files and list filenames". | ||
111 | ``` | ||
112 | gist config action 'cat *; ls' | ||
113 | ``` | ||
114 | |||
115 | Also, 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 | |||
120 | For example, use `gist config EDITOR code` to use VSCode instead. | ||
121 | |||
122 | ### protocol | ||
123 | **[Optional]** Protocol to clone git repo. Default to HTTPS | ||
124 | valid values are: | ||
125 | - https | ||
126 | - ssh | ||
127 | |||
128 | For example, use `gist config protocol ssh` to use SSH protocol instead. | ||
129 | |||
130 | ## Tips | ||
131 | ### Jump to gist repo | ||
132 | Sometimes you want to switch to the specified gist repo as working directory. | ||
133 | 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. | ||
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 | ||
145 | 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! | ||
146 | |||
147 | If [`tig`](https://github.com/jonas/tig) is installed, run the following command to configure it as custom action: | ||
148 | |||
149 | ``` | ||
150 | gist config action 'tig -all' | ||
151 | ``` | ||