README.md (12419B)
1 # gist - Manage your gist like a pro 2 3 All your notes, scripts, config files and snippets deserve version control and tagging! 4 `gist` is a simple **bash script** for gist management. 5 It is lightweight(~700LOC) and dependency-free! Helps you to boost coding workflow. 6 7 - [Getting Started](#Getting-Started) 8 - [Dependencies](#Dependencies) 9 - [Basic Commands](#Basic-Commands) 10 - [Update and clone gists from Github](#Update-and-clone-gists-from-Github) 11 - [List your gists](#List-your-gists) 12 - [Create a new gist](#Create-a-new-gist) 13 - [Modify a gist](#Modify-a-gist) 14 - [Clean unnecessary local repos](#Clean-unnecessary-local-repos) 15 - [Configuration](#Configuration) 16 - [Filter gists](#Filter-gists) 17 - [Filter by tags](#Filter-by-tags) 18 - [Filter by file languages](#Filter-by-file-languages) 19 - [Filter by pattern](#Filter-by-pattern) 20 - [Tips](#Tips) 21 - [Filter gists with pipe](#Filter-gists-with-pipe) 22 - [Git Workflow](#Git-Workflow) 23 - [Useful action for gist repo](#Useful-action-for-gist-repo) 24 - [Suppress action](#Suppress-action) 25 - [Suppress hint](#Suppress-hint) 26 27 ## Getting Started 28 ```bash 29 # Install with script on GitHub Page 30 curl -L https://git.io/J3DXe -o gist # This shortened link points to the bash script 31 sudo install -m755 gist /usr/local/bin/gist # Install this script wherever you like 32 # Fetch your gists and clone them into ~/gist as git repos 33 gist fetch 34 # List your gists 35 gist 36 # Create a new gist 37 gist new 38 # Create private gist with files 'foo' and 'bar' 39 gist new -p foo bar 40 # Check information of your third gist 41 gist detail 3 42 # Get the path and cd to cloned repo with subshell 43 gist 3 44 # List your gists with tags instead of URL 45 gist tag 46 # Add tags to your third gist 47 gist tag 3 48 # Update the description of your third gist 49 gist edit 3 50 # Push changes in your third gist to the remote repo 51 gist push 3 52 # Delete gists with indices 3, 4 and 5 53 gist delete 3 4 5 54 # Or use Brace Expansion 55 gist delete {3..5} 56 # Export your third gist as a new Github repo with web page 57 gist github 3 58 # For more detail, read the helper message 59 gist help 60 ``` 61 62 ## Dependencies 63 OK...I lied, this script really depends on some very basic dev tools. 64 - **GNU coreutils** 65 Used to process text streams. Also, if you are on Mac and use `sed`, `tail` with BSD version, then it is still fine! 66 - **wget or curl** 67 Used to making request to `github.com`. 68 - **git** 69 Do not tell me you don't have it on your machine... 70 - **Python** 71 Both 2 and 3 works. It is used to process JSON response from `github.com` and launch default browser.(Only built-in modules are used) 72 73 ## Basic Commands 74 ### Update and clone gists from Github 75 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`) 76 - Automatically Clone/Pull each gist with git into a given folder. (default to `~/gist/`) 77 - Run `gist fetch star` to fetch your starred gist 78 - If token is not being set, then you cannot fetch your private gist 79 80 ### List your gists 81 Run `gist` to read index file (default to `~/gist/index`) and list your gists with the following format: 82 ``` 83 <index> <gist-URL> <files-number> <comments-number> <description> 84 ``` 85 86 like the following: 87 88  89 90 - Use `gist star` to show your starred gists 91 - Use `gist all` to show your and starred gists 92 - Index with prefix `s` is a starred gist, index with prefix `p` is a private gist 93 - There are colorful hints for each gist in the following cases: 94 - **working** 95 Some changes are made locally but not yet do `git commit`, or you are not in `master` branch 96 - **ahead** 97 Your local **HEAD** is yet to be applied to upstream 98 - **outdated** 99 Your local **HEAD** is differs from the last fetched gists, do `gist fetch` to refresh index file and pull if needed 100 101 ### Create a new gist 102 Run `gist new` to create a new gist 103 - You can create a new gist with 3 different ways: 104 1. type the content by hand, run `gist new` 105 2. use existing files, run `gist new <file1> <file2>...` 106 3. from STDIN, like `<command> | gist new` 107 - You can specify filename with `--file`, and description with `--desc`, like `gist new --file new --desc 'a new gist'` 108 - If you don't specify filename or description, a prompt will shows up! 109 110 ### Modify a gist 111 Run `gist <INDEX>` to enter sub-shell with working directory of the given gist index (by default action). You can do some trick with custom action.(See [action](#action) and [Tips](#Tips)) 112 113 Since now a gist is a local cloned repo, it is your business to do git commit and git push. Use `gist push <INDEX>` is not recommended. 114 115 ### Clean unnecessary local repos 116 Say you delete gists with command `gist delete <index-of-gist>...`, the local git repositories are still at `~/gist/`. 117 Run `gist clean` to move them into `/tmp/gist/`. 118 119 ## Configuration 120 `gist` stores your configuraion inside `~/.config/gist.conf`, with `<key>=<value>` format for each line. And just do `source ~/.config/gist.conf` at runtime. 121 122 `~/.config/gist.conf` is created automatically when you run `gist` at the first time, it only allows current user to read and write (permission 600). 123 124 Valid keys are [`user`](#user), [`token`](#token), [`folder`](#folder), [`auto_sync`](#auto_sync), [`action`](#action), [`EDITOR`](#EDITOR), [`protocol`](#protocol) and [`show_untagged`](#show_untagged). Use the following commands to set value: 125 ``` bash 126 # Set key with a given value 127 gist config <key> <value> 128 129 # Remove current value from a key 130 gist config <key> 131 132 # Or just modify ~/.config/gist.conf directly 133 gist config 134 ``` 135 Each key is for the following use cases: 136 137 ### user 138 Your Github username 139 140 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). 141 142 Use `gist config user <your-github-username>` to set the value if needed. 143 144 ### token 145 Your Github API token for the given username. It's scope should be with `gist`. 146 147 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. 148 149 Use `gist config token <your-github-api-token>` to set the value if needed. 150 151 ### folder 152 **[Optional]** The folder you stores index file and git repos for each your gists and starred gists. Default to `~/gist/` if not being set. 153 154 Use `gist config folder <prefered-directory>` to set the value if needed. 155 156 ### auto_sync 157 **[Optional]** Automatically clone/update your gists and starred gists as git repos when doing `gist fetch`. Default to be `true`. 158 159 Use `gist config auto_sync false` to disable this feature. 160 161 ### action 162 **[Optional]** A custom action is performed when you do `gist <INDEX>` (like `gist 3` for your third gist). If is being set, `gist` will `cd` to the cloned repo, and just simply use `eval` to perform action. 163 164 For example, you can use the following command to 165 **print the filename and its content of all files inside the given gist** 166 ```bash 167 gist config action 'tail -n +1 *' 168 ``` 169 170 If action is not being set, then a default action will be performed: 171 ```bash 172 # Enter sub-shell with current shell or bash 173 ${SHELL:-bash} 174 ``` 175 176 Also, if you run `gist <INDEX>` with `--no-action`(or `-n`), then action would be ignored. 177 178 ### EDITOR 179 **[Optional]** Editor to open `~/.config/gist.conf`. Default to be `vi` . 180 181 For example, use `gist config EDITOR code` to use VSCode instead. 182 183 ### protocol 184 **[Optional]** Protocol to clone git repo. Default to be `HTTPS` 185 186 Valid values are: 187 - https 188 - ssh 189 190 For example, use `gist config protocol ssh` to use SSH protocol instead. 191 192 ### show_untagged 193 **[Optional]** Whether to show untagged gists when using [`gist tag`](#List-gists-with-tags). Default to be `true` 194 195 Use `gist config show_untagged false` to disable this feature. 196 197 ## Filter gists 198 ### Filter by tags 199 `gist` treats **trailing hashtags** inside gist description as tags. For example, if a description is: 200 ``` 201 [Title] this is description #tag1 #tag2 202 ``` 203 When [`gist`](#List-your-gists) is performed, it only display description with part: `[Title] this is description`, and treat the trailing hashtags as tags of a gist. 204 205 #### Tag a gist 206 You can use the following command to add/remove tags: 207 ```bash 208 # tag your third gist 209 gist tag 3 210 ``` 211 After it is finished, `gist` just calls Github API to apply new description onto the given gist. 212 213 #### List gists with tags 214 Use sub-command `tag` to list gists with tags instead of URLs. 215 ```bash 216 # show tags for your gists 217 gist tag 218 ``` 219  220 221 #### Filter gists with tags 222 If arguments after `gist tag` are not indices of gist, then they will be treated as tag values. The output will be a list of gists with those tags 223 ```bash 224 # Filter gists with tag1 and tag2 225 gist tag tag1 tag2 226 ``` 227  228 229 You can also use regex pattern as tag value: 230 ```bash 231 # only show tagged gists 232 gist tag .+ 233 ``` 234 235 #### Show existing tags 236 Use sub-command `tags` to show existing tags and pinned tags. They are sorted alphabetically. 237 ```bash 238 gist tags 239 ``` 240  241 242 #### Pin/Unpin tags 243 Say you are working with gists with some meaningful tags. You can use sub-command `pin` to pin them, and filter your gists with pinned tags 244 ```bash 245 # Pin tag1 and tag2, If a tag is pinned, then unpin it 246 gist pin tag1 tag2 247 # Disply gists with pinned tags 248 gist pin 249 ``` 250  251 252 ### Filter by pattern 253 You can search gists with pattern in description, filename or file contents with sub-command `grep` 254 ```bash 255 # search by a simple string 256 gist grep string 257 # search by a pattern(heading string in a line) 258 gist grep '^string' 259 ``` 260 261 ### Filter by file languages 262 #### List gists with languages 263 You can use sub-command `lan` to List gists with file languages instead of URLs. 264 ```bash 265 # show languages for your gists 266 gist lan 267 ``` 268  269 270 #### Filter gists with languages 271 ```bash 272 # Filter gists with files in Shell and Yaml format 273 gist lan LANGUAGE1 LANGUAGE2... 274 ``` 275  276 277 ### Index Range 278 You can specify the range of indices, works both on your owned gists and starred gists. 279 ```bash 280 # only show gists with index 5 to 10 281 gist 5-10 282 # show gists from index 5 283 gist 5- 284 # show starred gists only to index s10 285 gist -s10 286 # only show gists with index 1 to 20 287 seq 20 | gist 288 ``` 289 290 ## Tips 291 292 ### Filter gists with pipe 293 If `STDIN` is from a pipe, then `gist` will only process gists with **indices in the first column**. So, you can concatenate the output of each sub-command. 294 ```bash 295 # only show gists with index 1 to 20 296 seq 20 | gist 297 # List starred gist with Yaml file 298 gist star | gist lan Yaml 299 # Only List gists with tag1, pattern1 in description/filenames/contents and contains shell script 300 gist tag tag1 | gist grep pattern1 | gist lan SHELL 301 ``` 302 303 ### Git Workflow 304 Each gist is a git repository. 305 Although there are some limits on `git push`, like sub-directory is prohibited. But guess what? 306 1. Push another branch to `github.com` is allowed. 307 2. Push tags is also allowed. And like repos in `github.com`, you can get source file by reference with URL: 308 ``` 309 https://codeload.github.com/gist/<gist_id>/tar.gz/<YOUR TAG or BRANCH> 310 ``` 311 312 ### Useful action for gist repo 313 I strongly recommend using [`tig`](https://github.com/jonas/tig) as your custom [action](#action). It is the most powerful git CLI tool as far as I know, and also easy to get in most of the Linux distros or Homebrew for mac. Give it a try! 314 315 If [`tig`](https://github.com/jonas/tig) is installed, run the following command to configure it as custom action: 316 317 ```bash 318 gist config action 'tig -all' 319 ``` 320 `tig` interface for history diagram: 321  322 323 324 ### Suppress action 325 If [`action`](#action) is not being set, you will enter sub-shell by default. If you want suppress it and do not want to type `--no-action` every time, just use command `ture` to do nothing. 326 ``` 327 gist config action 'true' 328 ``` 329 330 ### Suppress hint 331 There are several environment variables or arguments can suppress hint or user confirm, like: 332 ```bash 333 # List gists without hint 334 hint=false gist 335 336 # Just print the repo path with a given index 337 gist 3 --no-action 338 # Or shorter argument 339 gist 3 -n 340 341 # Delete your third gist without confirmation 342 gist delete 3 --force 343 ```