Skip to content

Commit

Permalink
doc: update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
mehran-prs committed May 19, 2024
1 parent 687c32c commit 75f676d
Showing 1 changed file with 33 additions and 32 deletions.
65 changes: 33 additions & 32 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,28 +15,24 @@
</p>


Snip is a command-line snippet manager.
Snip is a simple and minimal command-line snippet manager.

### Features

- View your snippets on command line.
- Manage (create|edit|Delete) your snippets using your favorite editor.
- Auto-completion on the command-line for your snippet names (supports `bash`, `zsh`, `fish` and `powershell`).
- Seamlessly integration with `fzf` to fuzzy find your snippets.
- Render your snippets nicely (you can set your custom commands to render files)
- Treat your snippets directory like a git repo, sync them with your git repo by single command.

Snip helps you manage snippets in cmd.
- View your snippets on command line and also manage them (create, edit, delete) using your favorite editor.
- Command-line auto-completion for the snippets names (supports `bash`, `zsh`, `fish` and `powershell`).
- Seamlessly integration with `fzf` to provide fuzzy search.
- Syntax highlighting (using `bat` and `glow` by default) and Git integration

### Usage

#### View a snippet

- Run `snip {snippet_name}` to view a snippet (press tab to see autocompletion suggestions).
- Run `snip {snippet_name}` to view a snippet.
- If you've
enabled [`fzf` shell integration](https://github.com/junegunn/fzf?tab=readme-ov-file#setting-up-shell-integration) in
you bash or zsh,
you can find snippets by fuzzy search by typing `**` and pressing tab.
you can find snippets by fuzzy search. e.g., type `snip **` and pres tab.

![snip view snippets](docs/images/snip-view.gif)

Expand All @@ -56,15 +52,15 @@ Snip helps you manage snippets in cmd.
```bash
git pull origin
git add -A
git commit -m "{users_provided_message | default_message}"
git commit -m "{your_provided_message | default_message}"
git push origin
```

![snip sync snippets](docs/images/snip-sync.gif)


__Note__: before running `git sync` command for first time, you need to initialize git in your snippets directory and
also set upstream of your default branch. something like the following commands:
> [!NOTE]
> before running `git sync` for first time, you need to initialize git in your snippets directory and
> also set upstream of your default branch. something like the following commands:
```bash
cd $(snip dir)
Expand All @@ -75,19 +71,18 @@ git add -A && git commit -m "Initial commit"
git push -u origin main
```



### Prerequisites

- [`bat`](https://github.com/sharkdp/bat) and [`glow`](https://github.com/charmbracelet/glow) to render your snippets. (
you can customize `snip` to use other tools to
render files)
- (optional): [`fzf`](https://github.com/junegunn/fzf) to enable fuzzy-finder autocompletion feature.
- (optional): [`fzf`](https://github.com/junegunn/fzf) to enable fuzzy-search in auto-completion.
(currently `fzf` autocompletion feature is supported just in `bash` and `zsh`).

### Getting started

- [Install prerequisites](#prerequisites): Install `bat` and `glow` commands. and optionally(recommended) fzf if you're
- [Install prerequisites](#prerequisites): Install `bat` and `glow` commands. and optionally(recommended) `fzf` if
you're
using bash or zsh.
- [Install the snip command](#installation).
- [Enable auto-completion](#setting-up-shell-integration)
Expand All @@ -108,7 +103,6 @@ Or get pre-compiled executables [here](http://github.com/mehran-prs/snip/release
### Setting up shell integration

Add the following line to your shell configuration file.
__Note__: To enable fuzzy completion of `fzf`, the autocompletion feature must be enabled on your `fzf` tool.

* bash
```sh
Expand All @@ -126,18 +120,23 @@ __Note__: To enable fuzzy completion of `fzf`, the autocompletion feature must b
snip completion fish | source
```

> [!NOTE]
> [fzf shell integration](https://github.com/junegunn/fzf?tab=readme-ov-file#setting-up-shell-integration) is a
> pre-requisite
> of snip fuzzy search in auto-completion.
### Customization

Set the following env variables to customize snip:

| Name | Default | Description |
|--------------------------|-----------------------------------------------------|---------------------------------------------------------------------------------|
| SNIP_DIR | ~/snippets | The snippets directory. It must be absolute path |
| SNIP_FILE_VIEWER_CMD | bat --style plain --paging never | The tool which renders non-markdown files in cmd |
| SNIP_MARKDOWN_VIEWER_CMD | glow | The tool which renders markdown files in cmd |
| SNIP_EDITOR | Value of the "EDITOR" env variable, otherwise "vim" | The editor which snip uses to let you edit snippets |
| SNIP_GIT | git | The git command which is uses to sync snippets with your git repository |
| SNIP_EXCLUDE | .git,.idea | comma-separated list of directories that you want to exclude in auto-completion |
| SNIP_DIR | `~/snippets` | The snippets directory. It must be absolute path |
| SNIP_FILE_VIEWER_CMD | `bat --style plain --paging never` | The tool which renders non-markdown files in cmd |
| SNIP_MARKDOWN_VIEWER_CMD | `glow` | The tool which renders markdown files in cmd |
| SNIP_EDITOR | Value of the `EDITOR` env variable, otherwise `vim` | The editor which snip uses to let you edit snippets |
| SNIP_GIT | `git` | The git command which it uses to sync snippets with your remote git repository |
| SNIP_EXCLUDE | `.git,.idea` | comma-separated list of directories that you want to exclude in auto-completion |
| SNIP_VERBOSE | "" | Enable verbose mode |
| SNIP_LOG_TMP_FILENAME | "" | Set a temporary log file. it's helpful in autocompletion debugging |

Expand Down Expand Up @@ -165,7 +164,7 @@ Flags:

I like to have multiple instances of the `snip` command under different names for multiple repositories. for example
`snip` to manage my snippets, and `tasks` to manage my tasks.
We can do that by creating a soft-link to the `snip` command(other solutions like aliasing doesn't work
We can do that by creating a soft-link to the `snip` command (other solutions like aliasing doesn't work
perfectly in auto-completion, at least for me :)) ),
for example to add the `tasks` command, follow these steps:

Expand All @@ -175,7 +174,8 @@ for example to add the `tasks` command, follow these steps:
ln -s $(whereis snip | awk '{print $2}') /usr/local/bin/tasks
```

- Update your shell config to set the directory of the `tasks` command and also enable autocompletion for it:
- Update your shell config to set the tasks directory for the `tasks` command(as its snippets directory) and also
enable autocompletion for it:

```bash
# Set the tasks directory (change to your own tasks directory)
Expand All @@ -186,9 +186,10 @@ source <(tasks completion zsh)

```

__Note__: You may wonder how the `tasks` command reads its directory path from `TASKS_DIR` env variable,
actually the snip tool reads env variables from `{APPNAME}_{ENV_NAME}` (in this case `TASKS_*`) and if
it was empty then reads from `SNIP_{ENV_NAME}`.
> [!NOTE]
> You may wonder how the `tasks` command reads its directory path from `TASKS_DIR` env variable instead of `SNIP_DIR`,
> actually the `snip` tool reads env variables from `{APPNAME}_{ENV_NAME}` (in this case `TASKS_*`) and if
> it was empty then reads from `SNIP_{ENV_NAME}`.
## Contributing

Expand All @@ -197,7 +198,7 @@ it was empty then reads from `SNIP_{ENV_NAME}`.
1. Create your feature branch (`git checkout -b my-new-feature`)
1. Make changes and add them (`git add .`)
1. Commit your changes (`git commit -m 'Add some feature'`)
1. Push to the branch (`git push origin my-new-feature`)
1. Push to the branch (`git push -u origin my-new-feature`)
1. Create new pull request

### Some helper commands for contributors
Expand Down

0 comments on commit 75f676d

Please sign in to comment.