Zsh Configuration

Built from makenew.github.io.

Zsh configuration as a zplug plugin.

Description

This configuration system works as a meta-plugin: all desired Zsh plugins are loaded from packages.zsh using zplug. Overall configuration then follows a normal plugin structure.

Display documentation of this Zsh configuration with

$ man zshrc

Bootstrapping a New Config

1. Clone the master branch of this repository with

   $ git clone --single-branch https://github.com/makenew/zshrc.git
   $ cd zshrc
   

   Optionally, reset to the latest release with

   $ git reset --hard zshrc-v1.2.1
   

2. Run

   $ ./makenew.sh
   

   and follow the prompts. This will replace the boilerplate, delete itself, stage changes for commit, remove tags, and set upstream. This script assumes the project repository will be hosted on GitHub. For an alternative location, you must update the URLs manually.

3. If choosing a license other than the one provided: update LICENSE.txt and the README License section with your chosen license.

4. After committing the initial changes, host your install.sh on GitHub pages with

   $ git checkout --orphan gh-pages
   $ git reset
   $ git add install.sh
   $ git commit -m 'Add install.sh'
   $ git push --set-upstream origin gh-pages
   $ git clean -fdx
   $ git checkout master
   

   Then, update the install URLs in this README (optionally, use Git.io to shorten them).

5. Document your configuration in doc/zshrc.1.txt.

Updating

If you want to pull in future updates from this skeleton, you can fetch and merge in changes from this repository.

Add this as a new remote with

$ git remote add upstream https://github.com/makenew/zshrc.git

You can then fetch and merge changes with

$ git fetch --no-tags upstream
$ git merge upstream/master

Changelog

Note that CHANGELOG.md is just a template for this skeleton. The actual changes for this project are documented in the commit history and summarized under Releases.

Installation

Due to the bootstrapping problem, ZDOTDIR must be set on zsh initialization by adding the line

export ZDOTDIR=$HOME/.config/zsh

to either /etc/zsh/zshenv or ~/.zshenv.

Automatic Install

You can install this via the command-line with either curl

$ curl -L https://git.io/vH987 | sh

or wget

$ wget https://git.io/vH987 -O - | sh

Manual Install

1. Install zplug.

2. Create $ZDOTDIR/.zshrc with

   # makenew/zshrc
   export ZSHRC_REPO=makenew/zshrc
   
   export ZDOTDIR="${ZDOTDIR:-${XDG_CONFIG_HOME:-$HOME/.config}/zsh}"
   export ZPLUG_HOME="${ZPLUG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/zplug}"
   export ZPLUG_CACHE_DIR="${ZPLUG_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/zplug}"
   
   zplug_loadfile="${ZPLUG_HOME}/repos/makenew/zshrc/packages.zsh"
   
   if [[ -e $zplug_loadfile ]]; then
     export ZPLUG_LOADFILE=$zplug_loadfile
   fi
   
   source "${ZPLUG_HOME}/init.zsh"
   
   if [[ ! -e $zplug_loadfile ]]; then
     zplug ${ZSHRC_REPO}
     zplug install
     export ZPLUG_LOADFILE=$zplug_loadfile
     source "${ZPLUG_HOME}/init.zsh"
   fi
   
   zplug ${ZSHRC_REPO}, use:env.zsh
   
   if ! zplug check; then
     zplug install
     echo '[zplug] Updating cache file: this may take up to a minute'
   fi
   
   zplug load

3. Open a new terminal session and wait for the initial install to complete.

Updating

Updating is handled via the normal zplug commands.

The provided shell function zshupg performs a one-step update.

Development and Testing

Source Code

The zshrc source is hosted on GitHub. Clone the project with

$ git clone https://github.com/makenew/zshrc.git

Local Development Mode

You can switch to development mode which will configure zplug to use the local directory as the plugin path.

First, follow the normal install steps if you haven't already. Then, switch to development mode with

$ ./install.sh dev

Optionally specify an existing branch to develop with

$ ./install.sh dev dev-branch

Switch out of development mode with

$ ./install.sh

Man Page

The man page is generated from doc/src/man1 using AsciiDoc with

$ a2x -f manpage -D doc/man/man1 doc/src/man1/*

Contributing

Please submit and comment on bug reports and feature requests.

To submit a patch:

1. Fork it (https://github.com/makenew/zshrc/fork).
2. Create your feature branch (git checkout -b my-new-feature).
3. Make changes.
4. Commit your changes (git commit -am 'Add some feature').
5. Push to the branch (git push origin my-new-feature).
6. Create a new Pull Request.

License

This software can be used freely, see The Unlicense. The copyright text appearing below and elsewhere in this repository is for demonstration purposes only and does not apply to this software.

This Zsh configuration is licensed under the MIT license.

Warranty

This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright holder or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.