From efafef8495f030501e0df59ccb76a598bbce3ae1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20Cornell=C3=A0?= Date: Fri, 9 Aug 2024 09:44:46 +0200 Subject: [PATCH] docs: improve several plugin READMEs and add one for `ssh` plugin --- plugins/aliases/README.md | 4 +- plugins/ansible/README.md | 2 - plugins/arduino-cli/README.md | 1 + plugins/asdf/README.md | 6 ++- plugins/chucknorris/README.md | 2 +- plugins/dbt/README.md | 6 +-- plugins/fancy-ctrl-z/README.md | 12 ++++- plugins/gatsby/README.md | 2 +- plugins/isodate/README.md | 4 +- plugins/jira/README.md | 48 ++++++++++--------- plugins/kube-ps1/README.md | 3 +- plugins/per-directory-history/README.md | 3 +- plugins/pipenv/README.md | 4 +- plugins/spring/README.md | 14 ++---- plugins/ssh/README.md | 16 +++++++ plugins/suse/README.md | 8 ++-- plugins/swiftpm/README.md | 2 - plugins/vagrant-prompt/README.md | 31 +++++++++++- .../vagrant-prompt/vagrant-prompt.plugin.zsh | 17 ------- plugins/vim-interaction/README.md | 16 +++---- plugins/xcode/README.md | 2 - plugins/yii2/README.md | 4 +- plugins/zsh-interactive-cd/README.md | 8 +++- 23 files changed, 124 insertions(+), 91 deletions(-) create mode 100644 plugins/ssh/README.md diff --git a/plugins/aliases/README.md b/plugins/aliases/README.md index 14f9c5c53..5a7e7dfc6 100644 --- a/plugins/aliases/README.md +++ b/plugins/aliases/README.md @@ -1,7 +1,5 @@ # Aliases cheatsheet -**Maintainer:** [@hqingyi](https://github.com/hqingyi) - With lots of 3rd-party amazing aliases installed, this plugin helps list the shortcuts that are currently available based on the plugins you have enabled. @@ -13,6 +11,8 @@ plugins=(aliases) Requirements: Python needs to be installed. +**Maintainer:** [@hqingyi](https://github.com/hqingyi) + ## Usage - `als`: show all aliases by group diff --git a/plugins/ansible/README.md b/plugins/ansible/README.md index dd0e1ce03..6a06962ee 100644 --- a/plugins/ansible/README.md +++ b/plugins/ansible/README.md @@ -1,7 +1,5 @@ # ansible plugin -## Introduction - The `ansible plugin` adds several aliases for useful [ansible](https://docs.ansible.com/ansible/latest/index.html) commands and [aliases](#aliases). To use it, add `ansible` to the plugins array of your zshrc file: diff --git a/plugins/arduino-cli/README.md b/plugins/arduino-cli/README.md index 91bda9067..821d72bbf 100644 --- a/plugins/arduino-cli/README.md +++ b/plugins/arduino-cli/README.md @@ -1,6 +1,7 @@ # Arduino CLI plugin This plugin adds completion for the [arduino-cli](https://github.com/arduino/arduino-cli) tool. + To use it, add `arduino-cli` to the plugins array in your zshrc file: ```zsh diff --git a/plugins/asdf/README.md b/plugins/asdf/README.md index f047860e2..4af69a75c 100644 --- a/plugins/asdf/README.md +++ b/plugins/asdf/README.md @@ -1,7 +1,5 @@ ## asdf -**Maintainer:** [@RobLoach](https://github.com/RobLoach) - Adds integration with [asdf](https://github.com/asdf-vm/asdf), the extendable version manager, with support for Ruby, Node.js, Elixir, Erlang and more. ### Installation @@ -28,3 +26,7 @@ asdf install nodejs latest asdf global nodejs latest asdf local nodejs latest ``` + +### Maintainer + +- [@RobLoach](https://github.com/RobLoach) diff --git a/plugins/chucknorris/README.md b/plugins/chucknorris/README.md index b51875de9..0562b3b59 100644 --- a/plugins/chucknorris/README.md +++ b/plugins/chucknorris/README.md @@ -1,6 +1,6 @@ # chucknorris -Chuck Norris fortunes plugin for Oh My Zsh. Perfectly suitable as MOTD. +Fortunes plugin for Chuck Norris for Oh My Zsh. Perfectly suitable as MOTD. To use it add `chucknorris` to the plugins array in you zshrc file. diff --git a/plugins/dbt/README.md b/plugins/dbt/README.md index e05d79cc3..74ae631cd 100644 --- a/plugins/dbt/README.md +++ b/plugins/dbt/README.md @@ -1,13 +1,11 @@ # dbt plugin -## Introduction - The `dbt plugin` adds several aliases for useful [dbt](https://docs.getdbt.com/) commands and [aliases](#aliases). To use it, add `dbt` to the plugins array of your zshrc file: -``` +```zsh plugins=(... dbt) ``` @@ -26,4 +24,4 @@ plugins=(... dbt) ## Maintainer -### [msempere](https://github.com/msempere) +- [msempere](https://github.com/msempere) diff --git a/plugins/fancy-ctrl-z/README.md b/plugins/fancy-ctrl-z/README.md index 82a4fd75e..7766c51eb 100644 --- a/plugins/fancy-ctrl-z/README.md +++ b/plugins/fancy-ctrl-z/README.md @@ -1,4 +1,14 @@ -# Use Ctrl-Z to switch back to Vim +# fancy-ctrl-z + +Allows pressing Ctrl-Z again to switch back to a background job. + +To use it, add `fancy-ctrl-z` to the plugins array in your zshrc file: + +```zsh +plugins=(... fancy-ctrl-z) +``` + +## Motivation I frequently need to execute random commands in my shell. To achieve it I pause Vim by pressing Ctrl-z, type command and press fg to switch back to Vim. diff --git a/plugins/gatsby/README.md b/plugins/gatsby/README.md index 36846a228..cc1bd392e 100644 --- a/plugins/gatsby/README.md +++ b/plugins/gatsby/README.md @@ -1,6 +1,6 @@ # gatsby autocomplete plugin -* Adds autocomplete options for all gatsby commands. +Adds autocomplete options for all gatsby commands. ## Requirements diff --git a/plugins/isodate/README.md b/plugins/isodate/README.md index 1ec75b2d4..5329310c2 100644 --- a/plugins/isodate/README.md +++ b/plugins/isodate/README.md @@ -1,7 +1,5 @@ # Isodate plugin -**Maintainer:** [@Frani](https://github.com/frani) - This plugin adds completion for the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), as well as some aliases for common Date commands. @@ -11,6 +9,8 @@ To use it, add `isodate` to the plugins array in your zshrc file: plugins=(... isodate) ``` +**Maintainer:** [@Frani](https://github.com/frani) + ## Aliases | Alias | Command | Description | diff --git a/plugins/jira/README.md b/plugins/jira/README.md index 1c6930298..7cfb81b19 100644 --- a/plugins/jira/README.md +++ b/plugins/jira/README.md @@ -1,16 +1,18 @@ -# Jira plugin # - -CLI support for JIRA interaction - -## Description ## +# Jira plugin This plugin provides command line tools for interacting with Atlassian's [JIRA](https://www.atlassian.com/software/jira) bug tracking software. +To use it, add `jira` to the plugins array in your zshrc file: + +```zsh +plugins=(... jira) +``` + The interaction is all done through the web. No local installation of JIRA is necessary. In this document, "JIRA" refers to the JIRA issue tracking server, and `jira` refers to the command this plugin supplies. -## Usage ## +## Usage This plugin supplies one command, `jira`, through which all its features are exposed. Most forms of this command open a JIRA page in your web browser. @@ -18,19 +20,19 @@ This plugin supplies one command, `jira`, through which all its features are exp `jira help` or `jira usage` will print the below usage instructions -| Command | Description | -| :------------ | :-------------------------------------------------------- | -| `jira` | Performs the default action | -| `jira new` | Opens a new Jira issue dialogue | -| `jira ABC-123` | Opens an existing issue | -| `jira ABC-123 m` | Opens an existing issue for adding a comment | -| `jira dashboard [rapid_view]` | Opens your JIRA dashboard | -| `jira mine` | Queries for your own issues | -| `jira tempo` | Opens your JIRA Tempo | -| `jira reported [username]` | Queries for issues reported by a user | -| `jira assigned [username]` | Queries for issues assigned to a user | -| `jira branch` | Opens an existing issue matching the current branch name | -| `jira help` | Prints usage instructions | +| Command | Description | +| :---------------------------- | :------------------------------------------------------- | +| `jira` | Performs the default action | +| `jira new` | Opens a new Jira issue dialogue | +| `jira ABC-123` | Opens an existing issue | +| `jira ABC-123 m` | Opens an existing issue for adding a comment | +| `jira dashboard [rapid_view]` | Opens your JIRA dashboard | +| `jira mine` | Queries for your own issues | +| `jira tempo` | Opens your JIRA Tempo | +| `jira reported [username]` | Queries for issues reported by a user | +| `jira assigned [username]` | Queries for issues assigned to a user | +| `jira branch` | Opens an existing issue matching the current branch name | +| `jira help` | Prints usage instructions | ### Jira Branch usage notes @@ -43,7 +45,7 @@ This is also checks if the prefix is in the name, and adds it if not, so: "MP-12 -#### Debugging usage #### +#### Debugging usage These calling forms are for developers' use, and may change at any time. @@ -51,7 +53,7 @@ These calling forms are for developers' use, and may change at any time. jira dumpconfig # displays the effective configuration ``` -## Setup ## +## Setup The URL for your JIRA instance is set by `$JIRA_URL` or a `.jira_url` file. @@ -68,7 +70,7 @@ echo "https://jira.atlassian.com" >> .jira-url (Note: The current implementation only looks in the current directory for `.jira-url` and `.jira-prefix`, not up the path, so if you are in a subdirectory of your project, it will fall back to your default JIRA URL. This will probably change in the future though.) -### Variables ### +### Variables * `$JIRA_URL` - Your JIRA instance's URL * `$JIRA_NAME` - Your JIRA username; used as the default user for `assigned`/`reported` searches @@ -79,6 +81,6 @@ echo "https://jira.atlassian.com" >> .jira-url * `$JIRA_TEMPO_PATH` - Your JIRA tempo url path; defaults to "/secure/Tempo.jspa" -### Browser ### +### Browser Your default web browser, as determined by how `open_command` handles `http://` URLs, is used for interacting with the JIRA instance. If you change your system's URL handler associations, it will change the browser that `jira` uses. diff --git a/plugins/kube-ps1/README.md b/plugins/kube-ps1/README.md index dd49eff39..be3c184be 100644 --- a/plugins/kube-ps1/README.md +++ b/plugins/kube-ps1/README.md @@ -1,5 +1,4 @@ -kube-ps1: Kubernetes prompt for bash and zsh -============================================ +# kube-ps1: Kubernetes prompt for bash and zsh A script that lets you add the current Kubernetes context and namespace configured on `kubectl` to your Bash/Zsh prompt strings (i.e. the `$PS1`). diff --git a/plugins/per-directory-history/README.md b/plugins/per-directory-history/README.md index 11150b059..2816c11ba 100644 --- a/plugins/per-directory-history/README.md +++ b/plugins/per-directory-history/README.md @@ -1,5 +1,4 @@ -per-directory-history plugin ----------------------------- +# per-directory-history plugin This plugin adds per-directory history for zsh, as well as a global history, and the ability to toggle between them with a keyboard shortcut. This is a diff --git a/plugins/pipenv/README.md b/plugins/pipenv/README.md index e78ef0e3b..429b6f186 100644 --- a/plugins/pipenv/README.md +++ b/plugins/pipenv/README.md @@ -1,6 +1,6 @@ # Pipenv -## Installation +This plugin provides some features to simplify the use of [Pipenv](https://pipenv.pypa.io/) while working on ZSH. In your `.zshrc` file, add `pipenv` to the plugins section @@ -10,8 +10,6 @@ plugins=(... pipenv ...) ## Features -This plugin provides some features to simplify the use of Pipenv while working on ZSH. - - Adds completion for pipenv - Auto activates and deactivates pipenv shell - Adds short aliases for common pipenv commands diff --git a/plugins/spring/README.md b/plugins/spring/README.md index 816181326..b93402000 100644 --- a/plugins/spring/README.md +++ b/plugins/spring/README.md @@ -1,16 +1,12 @@ # Spring Boot oh-my-zsh plugin -oh-my-zsh Spring Boot plugin -## Spring Boot autocomplete plugin +Adds autocomplete options for all [Spring Boot](https://spring.io/projects/spring-boot) commands. -- Adds autocomplete options for all spring boot commands. +To use it, add `spring` to the plugins array in your zshrc file: -## Manual Install - - $ cd ~/.oh-my-zsh/plugins - $ git clone git@github.com:linux-china/oh-my-zsh-spring-boot-plugin.git spring - -Adjust your .zshrc file and add spring to plugins=(...) +```zsh +plugins=(... spring) +``` ## Tips diff --git a/plugins/ssh/README.md b/plugins/ssh/README.md new file mode 100644 index 000000000..3dd32ec76 --- /dev/null +++ b/plugins/ssh/README.md @@ -0,0 +1,16 @@ +# ssh plugin + +This plugin provides host completion based off of your `~/.ssh/config` file, and adds +some utility functions to work with SSH keys. + +To use it, add `ssh` to the plugins array in your zshrc file: + +```zsh +plugins=(... ssh) +``` + +## Functions + +- `ssh_rmhkey`: remove host key from known hosts based on a host section name from `.ssh/config`. +- `ssh_load_key`: load SSH key into agent. +- `ssh_unload_key`: remove SSH key from agent. diff --git a/plugins/suse/README.md b/plugins/suse/README.md index f37ec1695..e1e3aad29 100644 --- a/plugins/suse/README.md +++ b/plugins/suse/README.md @@ -1,8 +1,6 @@ # suse -**Maintainer**: [r-darwish](https://github.com/r-darwish) - -Alias for Zypper according to the official Zypper's alias +Aliases for [Zypper](https://en.opensuse.org/Portal:Zypper) according to the official Zypper's alias To use it add `suse` to the plugins array in you zshrc file. @@ -10,6 +8,8 @@ To use it add `suse` to the plugins array in you zshrc file. plugins=(... suse) ``` +**Maintainer**: [r-darwish](https://github.com/r-darwish) + ## Main commands | Alias | Commands | Description | @@ -79,6 +79,7 @@ Related: [#9798](https://github.com/ohmyzsh/ohmyzsh/pull/9798). | zrr | `sudo zypper rr` | remove repositories | ## Services commands + | Alias | Commands | Description | | ----- | ------------------ | -------------------------------------------------------------- | | zas | `sudo zypper as` | adds a service specified by URI to the system | @@ -88,6 +89,7 @@ Related: [#9798](https://github.com/ohmyzsh/ohmyzsh/pull/9798). | zls | `zypper ls` | list services defined on the system | ## Package Locks Management commands + | Alias | Commands | Description | | ----- | ---------------- | ----------------------------------- | | zal | `sudo zypper al` | add a package lock | diff --git a/plugins/swiftpm/README.md b/plugins/swiftpm/README.md index e5b4752e4..babbf4d66 100644 --- a/plugins/swiftpm/README.md +++ b/plugins/swiftpm/README.md @@ -1,7 +1,5 @@ # Swift Package Manager -## Description - This plugin provides a few utilities that make you faster on your daily work with the [Swift Package Manager](https://github.com/apple/swift-package-manager), as well as autocompletion for Swift 5.9. To start using it, add the `swiftpm` plugin to your `plugins` array in `~/.zshrc`: diff --git a/plugins/vagrant-prompt/README.md b/plugins/vagrant-prompt/README.md index dd0ca363b..0720f4bde 100644 --- a/plugins/vagrant-prompt/README.md +++ b/plugins/vagrant-prompt/README.md @@ -1,6 +1,33 @@ +# vagrant-prompt + This plugin prompts the status of the Vagrant VMs. It supports single-host and multi-host configurations as well. -Look inside the source for documentation about custom variables. +To use it, add `vagrant-prompt` to the plugins array in your zshrc file: -Alberto Re +```zsh +plugins=(... vagrant-prompt) +``` + +**Alberto Re ** + +## Usage + +To display Vagrant info on your prompt add the `vagrant_prompt_info` to the +`$PROMPT` or `$RPROMPT` variable in your theme. Example: + +```zsh +PROMPT='%{$fg[$NCOLOR]%}%B%n%b%{$reset_color%}:%{$fg[blue]%}%B%c/%b%{$reset_color%} $(vagrant_prompt_info)$(svn_prompt_info)$(git_prompt_info)%(!.#.$) ' +``` + +`vagrant_prompt_info` makes use of some custom variables. This is an example +definition: + +```zsh +ZSH_THEME_VAGRANT_PROMPT_PREFIX="%{$fg_bold[blue]%}[" +ZSH_THEME_VAGRANT_PROMPT_SUFFIX="%{$fg_bold[blue]%}]%{$reset_color%} " +ZSH_THEME_VAGRANT_PROMPT_RUNNING="%{$fg_no_bold[green]%}●" +ZSH_THEME_VAGRANT_PROMPT_POWEROFF="%{$fg_no_bold[red]%}●" +ZSH_THEME_VAGRANT_PROMPT_SUSPENDED="%{$fg_no_bold[yellow]%}●" +ZSH_THEME_VAGRANT_PROMPT_NOT_CREATED="%{$fg_no_bold[white]%}○" +``` diff --git a/plugins/vagrant-prompt/vagrant-prompt.plugin.zsh b/plugins/vagrant-prompt/vagrant-prompt.plugin.zsh index d7c76c3c9..29f4038c5 100644 --- a/plugins/vagrant-prompt/vagrant-prompt.plugin.zsh +++ b/plugins/vagrant-prompt/vagrant-prompt.plugin.zsh @@ -1,20 +1,3 @@ -# vim:ft=zsh ts=2 sw=2 sts=2 -# -# To display Vagrant infos on your prompt add the vagrant_prompt_info to the -# $PROMPT variable in your theme. Example: -# -# PROMPT='%{$fg[$NCOLOR]%}%B%n%b%{$reset_color%}:%{$fg[blue]%}%B%c/%b%{$reset_color%} $(vagrant_prompt_info)$(svn_prompt_info)$(git_prompt_info)%(!.#.$) ' -# -# `vagrant_prompt_info` makes use of some custom variables. This is an example -# definition: -# -# ZSH_THEME_VAGRANT_PROMPT_PREFIX="%{$fg_bold[blue]%}[" -# ZSH_THEME_VAGRANT_PROMPT_SUFFIX="%{$fg_bold[blue]%}]%{$reset_color%} " -# ZSH_THEME_VAGRANT_PROMPT_RUNNING="%{$fg_no_bold[green]%}●" -# ZSH_THEME_VAGRANT_PROMPT_POWEROFF="%{$fg_no_bold[red]%}●" -# ZSH_THEME_VAGRANT_PROMPT_SUSPENDED="%{$fg_no_bold[yellow]%}●" -# ZSH_THEME_VAGRANT_PROMPT_NOT_CREATED="%{$fg_no_bold[white]%}○" - function vagrant_prompt_info() { local vm_states vm_state if [[ -d .vagrant && -f Vagrantfile ]]; then diff --git a/plugins/vim-interaction/README.md b/plugins/vim-interaction/README.md index c2b45f1d8..437b48d99 100644 --- a/plugins/vim-interaction/README.md +++ b/plugins/vim-interaction/README.md @@ -1,5 +1,13 @@ # Vim Interaction # +The idea for this script is to give you some decent interaction with a running +GVim session. Normally you'll be running around your filesystem doing any +number of amazing things and you'll need to load some files into GVim for +editing, inspecting, destruction, or other bits of mayhem. This script lets you +do that. + +## Usage + The plugin presents a function called `callvim` whose usage is: usage: callvim [-b cmd] [-a cmd] [file ... fileN] @@ -9,14 +17,6 @@ The plugin presents a function called `callvim` whose usage is: file The file to edit ... fileN The other files to add to the argslist -## Rationale ## - -The idea for this script is to give you some decent interaction with a running -GVim session. Normally you'll be running around your filesystem doing any -number of amazing things and you'll need to load some files into GVim for -editing, inspecting, destruction, or other bits of mayhem. This script lets you -do that. - ## Aliases ## There are a few aliases presented as well: diff --git a/plugins/xcode/README.md b/plugins/xcode/README.md index 27d6a228b..ac79f728d 100644 --- a/plugins/xcode/README.md +++ b/plugins/xcode/README.md @@ -1,7 +1,5 @@ # Xcode -## Description - This plugin provides a few utilities that can help you on your daily use of Xcode and iOS development. To start using it, add the `xcode` plugin to your `plugins` array in `~/.zshrc`: diff --git a/plugins/yii2/README.md b/plugins/yii2/README.md index 345b66eb6..e6c71f23e 100644 --- a/plugins/yii2/README.md +++ b/plugins/yii2/README.md @@ -1,7 +1,7 @@ # Yii2 autocomplete plugin -* Adds autocomplete commands and subcommands for yii. +Adds autocomplete commands and subcommands for [yii](https://www.yiiframework.com/). ## Requirements -Autocomplete works from directory where your `yii` file contains. +Autocomplete works from directory where your `yii` file is contained. diff --git a/plugins/zsh-interactive-cd/README.md b/plugins/zsh-interactive-cd/README.md index 4bffbf04a..29812a295 100644 --- a/plugins/zsh-interactive-cd/README.md +++ b/plugins/zsh-interactive-cd/README.md @@ -1,5 +1,7 @@ # zsh-interactive-cd +This plugin provides an interactive way to change directories in zsh using fzf. + ## Demo ![demo](demo.gif) @@ -8,7 +10,11 @@ 1. Install [fzf](https://github.com/junegunn/fzf) by following its [installation instruction](https://github.com/junegunn/fzf#installation). -2. Source `zsh-interactive-cd.plugin.zsh` in `.zshrc`. +2. Add `zsh-interactive-cd` to your plugin list in `~/.zshrc`: + + ```zsh + plugins=(... zsh-interactive-cd) + ``` ## Usage