Skip to content

divine-bundles/essentials

BranchesTags

Repository files navigation

Deployment bundle essentials

A deployment bundle for Divine.dotfiles

The deployment bundle essentials for Divine.dotfiles is a collection of opinionated system set-up scripts. It is intended as a useful starting point for any Unix-like box.

(Additionally, this bundle showcases the recommended use of the mechanisms built into the current version of the Divine.dotfiles framework.)

Bundle name

essentials
Deployments

10
Divinefile entries

9
Attached bundle location

state/bundles/divine-bundles/essentials
Table of Contents

Description

Once the bundle is fully installed, and the shell reloaded, voilà:

  • Zsh is the default shell.

  • Zsh is augmented with completions, syntax highlighting, and auto-suggestions.

  • Basic necessities, such as Git, Vim, and GnuPG are available.

  • Both oh-my-zsh and Bash-it frameworks are installed and loaded.

  • A minimalistic theme for both shell frameworks is active.

  • Opinionated configs are plugged in for Git, Vim, Bash, and Zsh.

  • Any pre-existing files that have gotten in the way are safely backed up or re-used.

All of the above is controlled and customized through the key configuration files, which are located at ~/.grail/assets/.

Table 1. Overview of asset directories for the bundle essentials

~/.grail/assets/bash-it/ †

Custom assets for the Bash-it shell framework.

~/.grail/assets/brewfile/ †

The Brewfile, maintained on macOS.

~/.grail/assets/config-git/

The global configuration for Git.

~/.grail/assets/config-shell/

The startup scripts (runcoms) for Bash and Zsh.

~/.grail/assets/config-vim/

The global configuration for Vim.

~/.grail/assets/home-dirs/ †

The file home-dirs.cfg defines a sub-directory tree to be maintained under the home directory.

~/.grail/assets/oh-my-zsh/ †

Custom assets for the oh-my-zsh shell framework.

~/.grail/assets/portable-bin/

The container for the personal executables (this directory is maintained on the $PATH).

The dagger mark (†) meaning: in order for the modifications in that asset directory to take effect, the deployment must be (re-)installed.

Installing and uninstalling the bundle

The bundle essentials requires the Divine.dotfiles framework. The (un)installation guide assumes that Divine.dotfiles is installed into the default path: ~/.divine/, and that the shortcut command di is available.

Installing the bundle

With Divine.dotfiles already installed, the following Terminal command attaches the bundle essentials to the Grail directory:

di attach essentials

And the following Terminal command installs the attached bundle:

di install --bundle essentials

Any pre-existing files that get in the way are either re-used or backed up. Upon the uninstallation, such files are restored into their original places.

Uninstalling the bundle

The following Terminal command uninstalls the bundle essentials:

di remove --bundle essentials

And the following Terminal command detaches the bundle from the Grail directory:

di detach essentials

Bundled deployments

Divinefile

The bundle essentials includes a Divinefile that maintains the following system packages. Below is the list of the more prominent packages in the Divinefile. The Divinefile itself provides the full list. It is located in the root of the attached bundle’s directory at:

  • state/bundles/divine-bundles/essentials/Divinefile

Table 2. Highlights of Divinefile packages for the bundle essentials
Priority Package name Package notes

1000

git

1000

vim

1000

zsh

1000

wget

Except macOS, where it is pre-installed.

1000

curl

Except macOS, where it is pre-installed.

1000

gnupg

1000

tree

Deployment config-shell (333)

The config-shell deployment symlinks the configuration files ('runcoms') for Bash and Zsh into the home directory.

Installation map

Table 3. Installation map for the config-shell deployment

Symlinking

<asset-dir>/base/.bashprofile

⇒

~/.bashprofile

1

<asset-dir>/base/.zprofile

⇒

~/.zprofile

<asset-dir>/base/.bashrc

⇒

~/.bashrc

<asset-dir>/base/.zshrc

⇒

~/.zshrc

<asset-dir>/

⇒

~/.runcoms/

2 5
Installation

Symlinked; any pre-existing original backed up and replaced.

Removal

Unlinked; any backed up original restored.

Creating

⇒

~/.pre.bash

3

⇒

~/.pre.zsh

⇒

~/.pre.sh

⇒

~/.post.bash

⇒

~/.post.zsh

⇒

~/.post.sh

⇒

~/.hushlogin

4
Installation

Created, or re-used if pre-existing.

Removal

Removed, or untouched if re-used.

Included assets

  • The base runcoms (the .*profile and .*rc files recognized by Bash and Zsh) do little on top of sequentially sourcing the custom and box-specific runcoms.

  • The root of the asset directory is home for the custom runcoms.

    During the shell startup, both .bashrc and .zshrc source files from this directory, in the ascending alphanumerical order:

    • The .bashrc script sources every <name>.bash and every <name>.sh file.

    • The .zshrc script sources every <name>.zsh and every <name>.sh file.

    A sample set of opinionated runcoms is included.

  • The empty-ish box-specific runcoms are created in the home directory, and are not intended to leave the current machine:

    • Sourced before the custom runcoms:

      • ~/.pre.bash — exclusive to Bash.

      • ~/.pre.zsh — exclusive to Zsh.

      • ~/.pre.sh — universal.

        This particular runcom is pre-loaded with the definitions of the D__OS_FAMILY, D__OS_DISTRO, and D__OS_PKGMGR variables, which describe the current OS.

    • Sourced after the custom runcoms:

      • ~/.post.bash — exclusive to Bash.

      • ~/.post.zsh — exclusive to Zsh.

      • ~/.post.sh — universal.

  • ~/.hushlogin — the presence of this file in the home directory prevents any sort of textual banner from being printed durint the shell startup.

The following custom runcoms are provided with the deployment and contain an opinionated set of startup commands:

  • 00-config.bash — the general Bash configuration commands.

  • 00-config.zsh — the general Zsh configuration commands.

  • 01-bash-it.bash — the commands that initialize the Bash-it framework, if it is installed.

  • 01-oh-my-zsh.zsh — the commands that initialize the oh-my-zsh framework, if it is installed.

  • 02-env.sh — the environment variables for both shells, including the modifications of the $PATH variable.

  • 03-fixes.sh — the bug fixes for both shells.

  • 04-aliases.sh — the aliases for both shells.

  • 05-funcs.sh — the utility functions for both shells.

  • 06-addons.zsh — the commands that initialize the addons for Zsh.

Dependencies

The config-shell deployment is stand-alone.

However, it provides the support for other deployments in the current bundle (via the included custom runcoms):

  • 01-bash-it.bash — initializes the Bash-it framework for the bash-it deployment.

  • 01-oh-my-zsh.zsh — initializes the oh-my-zsh framework for the oh-my-zsh deployment.

  • 02-env.sh — ensures that all flavors of bin directory are on the $PATH variable for the home-dirs and portable-bin deployments.

  • 06-addons.zsh — initializes the Zsh addons for the zsh-addons deployment.

Deployment config-git (333)

The config-git deployment symlinks the configuration files for Git into the home directory.

Installation map

Table 4. Installation map for the config-git deployment

Symlinking

<asset-dir>/.gitconfig

⇒

~/.gitconfig

1

<asset-dir>/.gitattributes

⇒

~/.gitattributes

2
Installation

Symlinked; any pre-existing original backed up and replaced.

Removal

Unlinked; any backed up original restored.

Included assets

The two global configuration files for Git are provided:

  • .gitconfig — this file is interacted with by the git config --global command.

  • .gitattributes — this file globally influences certain Git operations by assigning attributes to the certain file path patterns.

A small amount of opinionated configuration is included in the specified files.

Dependencies

The config-git deployment is stand-alone.

The Divinefile included with the current bundle ensures that Git is installed.

Deployment config-vim (333)

The config-vim deployment symlinks the configuration and customization files for Vim into the home directory.

Installation map

Table 5. Installation map for the config-vim deployment

Symlinking

<asset-dir>/.vimrc

⇒

~/.vimrc

1

<asset-dir>/.ideavimrc

⇒

~/.ideavimrc

2

<asset-dir>/.vim/<name>/

⇒

~/.vim/<name>/

3
Installation

Symlinked; any pre-existing original backed up and replaced.

Removal

Unlinked; any backed up original restored.

Included assets

The native configuration files, containing an opinionated set of Vim startup commands:

  • .vimrc — the primary Vim configuration file.

    This file includes an installation command for the vim-plug (a minimalist Vim plugin manager) along with some plugins and settings.

  • .ideavimrc — the configuration file for the IdeaVim (a Vim emulation plugin for IDEs based on the IntelliJ Platform).

    If you don’t use any of the IntelliJ products, this file is harmless.

A number of Vim customization directories can be created in the root of the .vim/ directory, as containers for your customizations. One keymap is provided as an example:

  • keymap/shifted.vim — the 'Caps Lock' mode toggled by double-tapping j.

Overall, the following customization directories are supported by Vim:

  • after/ — the files to be loaded after the files in plugin/.

  • autoload/ — the files to be loaded when they are actually needed.

  • colors/ — the color schemes.

  • compiler/ — the compiler-related options in the current buffer.

  • doc/ — the custom plugin documentation.

  • ftdetect/ — the file type detection plugins.

  • ftplugin/ — the file type exclusive plugins.

  • indent/ — the file type exclusive indentation settings.

  • keymap/ — the key mapping files.

  • lang/ — the language files.

  • macros/

  • plugin/ — the standard plugins.

  • syntax/ — the syntax highlighting plugins.

  • tools/

The Vim help provides more information on the semantics of each directory.

Dependencies

The config-vim deployment is stand-alone.

The Divinefile included with the current bundle ensures that Vim is installed.

Deployment portable-bin (500)

The portable-bin deployment uses its own asset directory as a portable container for the personal executables.

Installation map

Table 6. Installation map for the portable-bin deployment

Symlinking

<asset-dir>/

⇒

~/.pbin/
Installation

Symlinked; any pre-existing original backed up and replaced.

Removal

Unlinked; any backed up original restored.

Included assets

Everything dropped into the portable-bin deployment’s asset directory immediately becomes available on $PATH. The portability is achieved when the Grail directory is synchronized across machines (as it is encouraged to be — e.g., using Dropbox or Github). The included asset directory starts out empty.

Dependencies

The portable-bin deployment depends on the config-shell deployment (included in the current bundle). The ~/.pbin/ directory is put on the $PATH variable from the runcom script at ~/.grail/assets/config-shell/02-env.sh.

Deployment home-dirs (500)

The home-dirs deployment maintains a stable tree of personal directories under the home directory.

Installation map

Table 7. Installation map for the home-dirs deployment

Creating

<dir-path> entries from <asset-dir>/home-dirs.cfg

⇒

~/<dir-path>/
Installation

Created, or re-used if pre-existing.

Removal

Removed, or untouched if re-used.

The home-dirs deployment:

  • parses the home-dirs.cfg file as a queue manifest;

  • treats entries as relative paths;

  • ensures that the paths correspond to sub-directories under the home directory.

Included assets

The home-dirs.cfg is a queue manifest. It uses the key-value pairs to denote sections or entries that are only relevant for particular OS’s. By default, every entry is relevant everywhere.

A whitespace-separated list of OS’s may be provided. The entire list may be negated by prepenting it with an exclamation mark (!).

A key-value that appears on a line of its own comes into effect for the remainder of the manifest, or until overridden. A key-value on the same line with an entry affects only that entry.

(os: debian)        relative/path/to/directory1   # Debian only
(os: macos bsd)     relative/path/to/directory2   # macOS/BSD only
(os: ! wsl cygwin)  relative/path/to/directory3   # Everything except WSL or Cygwin
(os: all)           relative/path/to/directory4   # 'all'/'any' are reserved values that denote any OS

The queue manifest syntax is documented in the framework’s documentation.

Dependencies

The home-dirs deployment is stand-alone.

Deployment zsh-addons (1000)

The zsh-addons deployment retrieves a number of community addons for Zsh: completions, syntax highlighting, and auto-suggestions.

Installation map

Table 8. Installation map for the zsh-addons deployment

Retrieving Github repositories

Repository zsh-users/zsh-completions

⇒

~/.zsh/zsh-users/zsh-completions/

Repository zsh-users/zsh-syntax-highlighting

⇒

~/.zsh/zsh-users/zsh-syntax-highlighting/

Repository zsh-users/zsh-autosuggestions

⇒

~/.zsh/zsh-users/zsh-autosuggestions/
Installation

Cloned/downloaded; any pre-existing original backed up and replaced.

Removal

Displaced; any backed up original restored.

Included assets

The zsh-addons deployment does not include any assets.

Dependencies

The zsh-addons deployment depends on the config-shell deployment (included in the current bundle). The retrieved addons are initialized from the runcom script at ~/.grail/assets/config-shell/06-addons.zsh.

Deployment zsh-default (1333)

The zsh-default deployment ensures that Zsh is the default shell for the current OS user.

Installation map

After some preparations (involving the /etc/shells file), the zsh-default deployment calls the chsh -s <path to zsh> command to change the default shell. Note that changing the default shell requires the user’s password. The password prompt will appear during the installation/removal.

Included assets

The zsh-default deployment does not include any assets.

Dependencies

The zsh-default deployment is stand-alone.

On some systems, the Divinefile included with the current bundle ensures that the chsh utility is installed.

Deployment brewfile (3000!)

The brewfile deployment maintains a set of system dependencies on macOS using the Brewfile.

The brewfile deployment is flagged as dangerous for two reasons:

  • Checking whether a Brewfile is installed or not is not reliable.

  • Uninstalling a Brewfile is not implemented on Homebrew’s side, and this deployment’s implementation is an approximation.

As a result of the flag, the brewfile deployment is not processed by the intervention utility, unless the --with-! option is given.

Installation map

Table 9. Installation map for the brewfile deployment

Installing

<asset-dir>/Brewfile

⇒

$ brew bundle install
Installation

Installed using brew bundle.

Removal

Removed by calling $ brew [cask] uninstall and $ brew untap.

The brewfile deployment delegates to the brew utility to install whatever items are listed in the provided Brewfile.

Uninstalling a Brewfile, however, is currently not supported by Homebrew. The brewfile deployment provides a workaround. Upon removal of this deployment, the Brewfile is read in reverse order: for every supported line, the appropriate Homebrew uninstallation command is called. This procedure is not an exact reverse of the installation due to the possible transient dependencies, as well as other factors.

Currently, the removal of the following Brewfile lines is supported:

  • tap <name> — taps will be untapped.

  • cask <name> — casks will be uninstalled.

  • brew <name> — bottles will be uninstalled.

Included assets

The included Brewfile starts up empty, and as such does nothing. The fundamental dependencies of the current bundle are handled by the included Divinefile. In other words, the Brewfile is kind of scoffed on around here.

Dependencies

The brewfile deployment is stand-alone.

On macOS, the Divine.dotfiles framework itself ensures that Homebrew is installed.

Deployment bash-it (3333)

The bash-it deployment introduces the Bash-it framework and custom assets for it into the home directory.

Installation map

Table 10. Installation map for the bash-it deployment

Retrieving Github repositories

Repository Bash-it/bash-it

⇒

~/.bash-it/

1
Installation

Cloned/downloaded; any pre-existing original backed up and replaced.

Removal

Displaced; any backed up original restored.

Symlinking

<asset-dir>/aliases/<name>.aliases.bash

⇒

~/.bash-it/aliases/available/<name>.aliases.bash

2

<asset-dir>/completion/<name>.completion.bash

⇒

~/.bash-it/completion/available/<name>.completion.bash

<asset-dir>/lib/<name>.bash

⇒

~/.bash-it/lib/<name>.bash

<asset-dir>/plugins/<name>.plugin.bash

⇒

~/.bash-it/plugins/available/<name>.plugin.bash

<asset-dir>/themes/<name>/<name>.theme.bash

⇒

~/.bash-it/themes/<name>/

3
Installation

Symlinked; any pre-existing original backed up and replaced.

Removal

Unlinked; any backed up original restored.

The bash-it deployment clones or downloads the Bash-it/bash-it repository into the ~/.bash-it/ directory. Having succeeded, it symlinks additional assets into the framework.

The Bash-it framework is installed with its included installation script. The --no-modify-config option is added because the current bundle already includes the necessary initialization commands.

Included assets

Blank sample files are provided for each kind of custom assets:

  • aliases/divine.aliases.bash

  • completion/divine.completion.bash

  • lib/divine.bash

  • plugins/divine.plugin.bash

A working minimalistic theme is provided for the custom themes:

  • themes/laidbare/laidbare.theme.bash

    This theme is also defaulted to in the provided initialization commands.

Dependencies

The bash-it deployment depends on the config-shell deployment (included in the current bundle). The retrieved Bash-it framework is initialized from the runcom script at ~/.grail/assets/config-shell/01-bash-it.bash. The same file may and should be used to customize the Bash-it framework’s loadout.

Deployment oh-my-zsh (3333)

The oh-my-zsh deployment introduces the oh-my-zsh framework and custom assets for it into the home directory.

Installation map

Table 11. Installation map for the oh-my-zsh deployment

Retrieving Github repositories

Repository robbyrussell/oh-my-zsh

⇒

~/.oh-my-zsh/

1
Installation

Cloned/downloaded; any pre-existing original backed up and replaced.

Removal

Displaced; any backed up original restored.

Symlinking

<asset-dir>/plugins/<name>/<name>.plugin.zsh

⇒

~/.oh-my-zsh/custom/plugins/<name>/

2

<asset-dir>/themes/<name>.zsh-theme

⇒

~/.oh-my-zsh/custom/themes/<name>.zsh-theme

3
Installation

Symlinked; any pre-existing original backed up and replaced.

Removal

Unlinked; any backed up original restored.

The oh-my-zsh deployment clones or downloads the robbyrussell/oh-my-zsh repository into the ~/.oh-my-zsh/ directory. Having succeeded, it symlinks additional assets into the framework.

The oh-my-zsh framework is installed only by cloning its Github repository. The included installation script (which normally adds initialization commands to the ~/.zshrc runcom) is not executed, because the current bundle already includes necessary initialization commands.

Included assets

A blank example file is provided for the custom plugins:

  • plugins/divine/divine.plugin.zsh

A working minimalistic theme is provided for the custom themes:

  • themes/laidbare.zsh-theme

    This theme is also defaulted to in the provided initialization commands.

Dependencies

The oh-my-zsh deployment depends on the config-shell deployment (included in the current bundle). The retrieved oh-my-zsh framework is initialized from the runcom script at ~/.grail/assets/config-shell/01-oh-my-zsh.zsh. The same file may and should be used to customize the oh-my-zsh framework’s loadout.

About

Deployment bundle 'essentials' for Divine.dotfiles

Topics

dotfiles bash framework dotfile-manager bash-scripting dotfiles-installer dotfiles-automation

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases 3

v1.0.2 — Axiom Latest
Dec 3, 2019
+ 2 releases

Packages

No packages published

Languages