|
| 1 | +# Zsh Configuration |
| 2 | + |
| 3 | +[<img src="https://makenew.github.io/makenew.svg" alt="Make New" height="20">](https://makenew.github.io/) |
| 4 | +[](https://github.com/makenew/zshrc/releases) |
| 5 | +[](./LICENSE.txt) |
| 6 | + |
| 7 | +> Built from [makenew.github.io](https://makenew.github.io/). |
| 8 | +
|
| 9 | +[Zsh] configuration as a [zplug] plugin. |
| 10 | + |
| 11 | +[Zsh]: https://www.zsh.org/ |
| 12 | +[zplug]: https://github.com/zplug/zplug |
| 13 | + |
| 14 | +## Description |
| 15 | + |
| 16 | +This configuration system works as a meta-plugin: |
| 17 | +all desired Zsh plugins are loaded from `packages.zsh` using [zplug]. |
| 18 | +Overall configuration then follows a normal plugin structure. |
| 19 | + |
| 20 | +Display documentation of this Zsh configuration with |
| 21 | + |
| 22 | +``` |
| 23 | +$ man zshrc |
| 24 | +``` |
| 25 | + |
| 26 | +### Bootstrapping a New Config |
| 27 | + |
| 28 | +1. Clone the master branch of this repository with |
| 29 | + |
| 30 | + ``` |
| 31 | + $ git clone --single-branch https://github.com/makenew/zshrc.git |
| 32 | + $ cd zshrc |
| 33 | + ``` |
| 34 | + |
| 35 | + Optionally, reset to the latest [release][Releases] with |
| 36 | + |
| 37 | + ``` |
| 38 | + $ git reset --hard zshrc-v1.0.0 |
| 39 | + ``` |
| 40 | + |
| 41 | +2. Run |
| 42 | + |
| 43 | + ``` |
| 44 | + $ ./makenew.sh |
| 45 | + ``` |
| 46 | + |
| 47 | + and follow the prompts. |
| 48 | + This will replace the boilerplate, delete itself, |
| 49 | + stage changes for commit, remove tags, and set upstream. |
| 50 | + This script assumes the project repository will be hosted on GitHub. |
| 51 | + For an alternative location, you must update the URLs manually. |
| 52 | + |
| 53 | +3. If [choosing a license][Choose a license] other than the one provided: |
| 54 | + update `LICENSE.txt` and the README License section with your chosen license. |
| 55 | + |
| 56 | +4. After committing the initial changes, host your `install.sh` on |
| 57 | + GitHub pages with |
| 58 | + |
| 59 | + ``` |
| 60 | + $ git checkout --orphan gh-pages |
| 61 | + $ git reset |
| 62 | + $ git add install.sh |
| 63 | + $ git commit -m 'Add install.sh' |
| 64 | + $ git push --set-upstream origin gh-page |
| 65 | + $ git clean -fdx |
| 66 | + $ git checkout master |
| 67 | + ``` |
| 68 | + |
| 69 | + Then, update the install URLs in this README |
| 70 | + (optionally, use [Git.io] to shorten them). |
| 71 | + |
| 72 | +5. Document your configuration in `doc/zshrc.1.txt`. |
| 73 | + |
| 74 | +[Choose a license]: http://choosealicense.com/ |
| 75 | +[Git.io]: https://git.io/ |
| 76 | +[Releases]: https://github.com/makenew/zshrc/releases |
| 77 | +[The Unlicense]: http://unlicense.org/UNLICENSE |
| 78 | + |
| 79 | +### Updating |
| 80 | + |
| 81 | +If you want to pull in future updates from this skeleton, |
| 82 | +you can fetch and merge in changes from this repository. |
| 83 | + |
| 84 | +Add this as a new remote with |
| 85 | + |
| 86 | +``` |
| 87 | +$ git remote add upstream https://github.com/makenew/zshrc.git |
| 88 | +``` |
| 89 | + |
| 90 | +You can then fetch and merge changes with |
| 91 | + |
| 92 | +``` |
| 93 | +$ git fetch --no-tags upstream |
| 94 | +$ git merge upstream/master |
| 95 | +``` |
| 96 | + |
| 97 | +#### Changelog |
| 98 | + |
| 99 | +Note that `CHANGELOG.md` is just a template for this skeleton. |
| 100 | +The actual changes for this project are documented in the commit history |
| 101 | +and summarized under [Releases]. |
| 102 | + |
| 103 | +## Installation |
| 104 | + |
| 105 | +Due to the bootstrapping problem, |
| 106 | +`ZDOTDIR` must be set on zsh initialization by adding the line |
| 107 | + |
| 108 | +``` |
| 109 | +export ZDOTDIR=$HOME/.config/zsh |
| 110 | +``` |
| 111 | + |
| 112 | +to either `/etc/zsh/zshenv` or `~/.zshenv`. |
| 113 | + |
| 114 | +### Automatic Install |
| 115 | + |
| 116 | +You can install this via the command-line with either curl |
| 117 | + |
| 118 | +``` |
| 119 | +$ curl -L https://git.io/vH987 | sh |
| 120 | +``` |
| 121 | + |
| 122 | +or wget |
| 123 | + |
| 124 | +``` |
| 125 | +$ wget https://git.io/vH987 -O - | sh |
| 126 | +``` |
| 127 | + |
| 128 | +### Manual Install |
| 129 | + |
| 130 | +1. Install [zplug]. |
| 131 | + |
| 132 | +2. Create `$ZDOTDIR/.zshrc` with |
| 133 | + |
| 134 | + ```zsh |
| 135 | + # makenew/zshrc |
| 136 | + |
| 137 | + export ZDOTDIR="${ZDOTDIR:-${XDG_CONFIG_HOME:-$HOME/.config}/zsh}" |
| 138 | + export ZPLUG_HOME="${ZPLUG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/zplug}" |
| 139 | + export ZPLUG_CACHE_DIR="${ZPLUG_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/zplug}" |
| 140 | + |
| 141 | + zplug_loadfile="${ZPLUG_HOME}/repos/makenew/zshrc/packages.zsh" |
| 142 | + |
| 143 | + if [[ -e $zplug_loadfile ]]; then |
| 144 | + export ZPLUG_LOADFILE=$zplug_loadfile |
| 145 | + fi |
| 146 | + |
| 147 | + source "${ZPLUG_HOME}/init.zsh" |
| 148 | + |
| 149 | + if [[ ! -e $zplug_loadfile ]]; then |
| 150 | + zplug 'makenew/zshrc' |
| 151 | + zplug install |
| 152 | + export ZPLUG_LOADFILE=$zplug_loadfile |
| 153 | + source "${ZPLUG_HOME}/init.zsh" |
| 154 | + fi |
| 155 | + |
| 156 | + zplug 'makenew/zshrc', use:env.zsh |
| 157 | + zplug 'makenew/zshrc', use:plugin |
| 158 | + |
| 159 | + if ! zplug check; then |
| 160 | + zplug install |
| 161 | + echo '[zplug] Updating cache file: this may take up to a minute' |
| 162 | + fi |
| 163 | + |
| 164 | + zplug load |
| 165 | + ``` |
| 166 | + |
| 167 | +3. Open a new terminal session and wait for the initial install to complete. |
| 168 | + |
| 169 | +### Updating |
| 170 | + |
| 171 | +Updating is handled via the normal [zplug commands]. |
| 172 | + |
| 173 | +The provided shell function `zshupg` performs a one-step update. |
| 174 | + |
| 175 | +[zplug commands]: https://github.com/zplug/zplug#2-commands-for-zplug |
| 176 | + |
| 177 | +## Development and Testing |
| 178 | + |
| 179 | +### Source Code |
| 180 | + |
| 181 | +The [zshrc source] is hosted on GitHub. |
| 182 | +Clone the project with |
| 183 | + |
| 184 | +``` |
| 185 | +$ git clone https://github.com/makenew/zshrc.git |
| 186 | +``` |
| 187 | + |
| 188 | +[zshrc source]: https://github.com/makenew/zshrc |
| 189 | + |
| 190 | +### Local Development Mode |
| 191 | + |
| 192 | +You can switch to development mode |
| 193 | +which will configure zplug to use the local |
| 194 | +directory as the plugin path. |
| 195 | + |
| 196 | +First, follow the normal install steps if you haven't already. |
| 197 | +Then, switch to development mode with |
| 198 | + |
| 199 | +``` |
| 200 | +$ ./install.sh dev |
| 201 | +``` |
| 202 | + |
| 203 | +Optionally specify an existing branch to develop with |
| 204 | + |
| 205 | +``` |
| 206 | +$ ./install.sh dev dev-branch |
| 207 | +``` |
| 208 | + |
| 209 | +Switch out of development mode with |
| 210 | + |
| 211 | +``` |
| 212 | +$ ./install.sh |
| 213 | +``` |
| 214 | + |
| 215 | +### Man Page |
| 216 | + |
| 217 | +The man page is generated from `doc/src/man1` using [AsciiDoc] with |
| 218 | + |
| 219 | +``` |
| 220 | +$ a2x -f manpage -D doc/man/man1 doc/src/man1/* |
| 221 | +``` |
| 222 | + |
| 223 | +[AsciiDoc]: http://asciidoc.org/ |
| 224 | + |
| 225 | +## Contributing |
| 226 | + |
| 227 | +Please submit and comment on bug reports and feature requests. |
| 228 | + |
| 229 | +To submit a patch: |
| 230 | + |
| 231 | +1. Fork it (https://github.com/makenew/zshrc/fork). |
| 232 | +2. Create your feature branch (`git checkout -b my-new-feature`). |
| 233 | +3. Make changes. |
| 234 | +4. Commit your changes (`git commit -am 'Add some feature'`). |
| 235 | +5. Push to the branch (`git push origin my-new-feature`). |
| 236 | +6. Create a new Pull Request. |
| 237 | + |
| 238 | +## License |
| 239 | + |
| 240 | +This software can be used freely, see [The Unlicense]. |
| 241 | +The copyright text appearing below and elsewhere in this repository |
| 242 | +is for demonstration purposes only and does not apply to this software. |
| 243 | + |
| 244 | +This Zsh configuration is licensed under the MIT license. |
| 245 | + |
| 246 | +## Warranty |
| 247 | + |
| 248 | +This software is provided by the copyright holders and contributors "as is" and |
| 249 | +any express or implied warranties, including, but not limited to, the implied |
| 250 | +warranties of merchantability and fitness for a particular purpose are |
| 251 | +disclaimed. In no event shall the copyright holder or contributors be liable for |
| 252 | +any direct, indirect, incidental, special, exemplary, or consequential damages |
| 253 | +(including, but not limited to, procurement of substitute goods or services; |
| 254 | +loss of use, data, or profits; or business interruption) however caused and on |
| 255 | +any theory of liability, whether in contract, strict liability, or tort |
| 256 | +(including negligence or otherwise) arising in any way out of the use of this |
| 257 | +software, even if advised of the possibility of such damage. |
0 commit comments