Say, there is a need to maintain a certain command line utility on every machine. Below is a sample deployment that does a scaled down version of that:

And here is what working with it looks like:

Dead simple. One wouldn’t need a framework for that. But there’s more.

The Divine.dotfiles framework is written in Bash. No attempt is made at POSIX compliancy, nor at cross-shell portability. Bash is chosen as the least common denominator across the modern operating systems.

At its very core, this framework is a sequential launcher of user-defined Bash code.

Since the deployments are essentially unrestricted Bash scripts, absolutely no illusion of security should be assumed. The framework creates a subshell for every sourced deployment, but security-wise that is pretty much it. Guarantees described in this section cover only the built-in mechanisms of the framework and the associated Divine bundles of deployments.

Interactivity

Zero data loss

Non-interference

Reversibility

Race conditions

Divine.dotfiles is installed, by default, into the ~/.divine/ directory, and is contained entirely in that directory, except:

• A symlink to the framework’s main script, intervene.sh, is created somewhere on $PATH.

• The Grail directory — home to user’s assets and deployments — is located, by default, at ~/.grail/.

• Deployments may affect the system pretty much anywhere.

The installed framework consists of the following main parts:

• A Unix-like OS. The following OS distributions are openly supported:

  • Debian

  • Fedora

  • FreeBSD

  • macOS

  • Ubuntu

  This list is incomplete; you can help by expanding it.

  The framework will work on other operating systems too, but without the support for packages (e.g., the Divinefiles will not work).

• Bash 3.2+ and either curl or wget.

  Git is not a hard requirement, but it is not a flaccid one either. Divine.dotfiles can be installed without Git. However, the framework will then proceed to vex the user with suggestions to auto-install it, until some day the y key is finally pressed.

The following single shell command installs the Divine.dotfiles framework:

Equivalently, the framework can be installed from a local copy of this repository (located not at the installation path) by running this command:

The documentation assumes that the framework has been installed with the optional shortcut command di. Still, all invocations of the di command are equivalent to executing the ./intervene.sh script in the root of the installation directory.

Installation options and overrides

The following single shell command uninstalls the Divine.dotfiles framework:

Equivalently, the framework can be uninstalled from a local copy of this repository (located anywhere) by running this command:

Also, an existing installation of Divine.dotfiles may be directed to uninstall itself:

One thing that framework uninstallation does not do is uninstall deployments. If not needed, any deployments that might have been installed must be removed manually before uninstalling Divine.dotfiles.

Uninstallation options and overrides

The following single shell command provides the introductory experience of the framework and deployments:

• installs the framework;

• attaches the essentials bundle of Divine deployments (distributed separately);

• installs the attached deployments.

All three sub-commands skip the trivial prompts (e.g., 'Are you sure?').

(The undo command is provided in the following section.)

Both the framework and deployments do not overwrite pre-existing files on the system without backing them up. Everything that is backed up is automatically restored upon removal.

After all installations are successful, it might be necessary to reload the shell (or even re-log into the system on macOS). This depends on whether the default shell has been changed.

What it does

Undoing the joy ride

Divine.dotfiles provides a command line interface via Divine intervention utility di. (Invoking the shortcut di is equivalent to executing the framework’s main script, intervene.sh.)

The first non-option argument, ROUTINE, can be any of the following:

The intervention routines, and the Divine.dotfiles overall, use a familiar set of rules for parsing options and arguments:

• The options and arguments are read left-to-right, word by word, separated by any unescaped whitespace.

  Whenever options override each other, the last option given wins. In the documentation, the overriding options have their descriptions grouped.

• Most options have single-character and long versions, which are equivalent.

• The single-character options can be combined (-CHARS).

  Words that start with one hyphen are interpreted as combined options.

• Words that start with two hyphens (--WORD) are interpreted as long options.

• The arguments and options can be freely mixed; all words after the optional separator (--) are interpreted as arguments.

• The two special options take priority over all other arguments/options:

  • -h, --help — outputs the help summary for the intervention utility.

  • --version — prints the version of the framework.

The three primary routines somewhat correspond to the three fundamental actions (functions) that the framework recognizes for any deployment:

• checking whether something is installed;

• installing it;

• and removing it.

The correspondence is not strictly one-to-one because all three primary routines do the checking part. The check routine stops there, but the install and remove routines proceed based on the check result.

check routine

$ di [-efhnoqvwy] [-b BUNDLE]… [--] c|check [NAME]…

install routine

$ di [-efhnoqvwy] [-b BUNDLE]… [--] i|install [NAME]…

remove routine

$ di [-efhnoqvwy] [-b BUNDLE]… [--] r|remove [NAME]…

Specifying deployments

Primary routine options

The framework treats any Github repository containing deployments as bundles of deployments.

When a bundle is attached to the particular Grail directory, its address is stored in the Grail stash, while a copy of the repository is pulled into the state directory. This way, the attached deployments are treated as if they are in the Grail, but the directory itself is not unnecessarily bloated.

On every invocation, the intervention utility synchronizes the stashed list of attached bundles with the copies in the state directory. Thus, transfering the Grail directory alone to another machine is enough to fully re-create the set of deployments.

The two bundle routines do what one might expect:

• attaching a bundle;

• detaching the previously attached bundle.

attach routine

$ di [-yn]… [--] a|attach [REPO]…

detach routine

$ di [-yn]… [--] d|detach [REPO]…

Specifying bundles

Bundle routine options

The Grail directory is the central hub for all user content. As such, it is the obvious target for version controlling and syncing.

The plug routine, unsurprisingly, imports an externally saved Grail directory, replacing the currently existing one.

For the ADDRESS argument, the following (case-insensitive) values are accepted:

• A Github repository in the form: username/repository.

• A path to a Git repository.

• A path to a local directory.

The framework iterates over possible interpretations of the argument and prompts the user for confirmation.

The repositories are cloned, the directories are copied. The pre-existing Grail directory is backed up in-place by appending the .bak suffix.

plug routine options

There are three parts of a Divine.dotfiles installation that are potentially cloned Git repositories:

• The framework itself.

• The Grail directory (if plugged from a repository).

• The attached bundles of deployments.

The update routine is a convenient tool that pulls the latest updates from the remote master branches of such repositories.

The update routine is three-pronged, and the user is free to choose which prongs to engage by providing or not providing arguments:

• f|framework updates the framework.

• g|grail — updates the cloned Grail directory.

• b|bundles — updates all attached bundles of deployments.

• Without any arguments, all three types of updates are performed.

update routine options

The minimal valid deployment is an empty file. As such, it does nothing but appear in the framework output.

Deployments are written in Bash syntax, with some syntax limitations on the metadata. Each deployment is sourced by the Bash interpreter no more than once per primary routine.

To be useful, a deployment may contain:

• Implementations of any or all of the primary functions.

• Assignments to the special pseudo-variables — the metadata.

It is highly recommended to not include any non-trivial Bash code outside of functions. Nothing will prevent things from going off the rails. There are no safety nets. Unless the intention is very well thought-out, Divine.dotfiles is only useful while the guidelines are followed.

The primary functions, or primaries, correspond to the three fundamental actions performed by a deployment:

• d_dpl_check — checks whether the deployment is installed or not.

• d_dpl_install — installs the deployment.

• d_dpl_remove — removes (reverses the previous installation of) the deployment.

The primary functions have the following ways of interacting with the framework:

• To 'talk' to the framework:

  • The return codes are the main vehicles of indicating status.

  • The add-statuses (specially named global variables) are available to tweak the behavior in some places.

• To 'hear' from the framework:

  • The indicator variables are populated by the framework with the relevant run-time data.

Primary function d_dpl_check

Primary function d_dpl_install

Primary function d_dpl_remove

Deployment metadata pose as definitions of Bash global variables and alter deployment’s appearance and behavior. In reality, the metadata 'assignments' are read from the file before the Bash interpreter sources it. The metadata are all optional; they may be given in any order and disjointly. However, the metadata must precede all other code of the deployment script.

• D_DPL_NAME=NAME

  The explicit name for the deployment. The implicit fallback name is the name of the deployment file sans the .dpl.sh suffix.

• D_DPL_DESC="DESCRIPTION TEXT"

  The one-line description of the deployment. For the user’s eyes only.

• D_DPL_PRIORITY=PRIORITY

  The priority of the deployment (a non-negative integer).

• D_DPL_FLAGS=FLAGS

  The single-character flags that cause special treatment.

• D_DPL_WARNING='WARNING TEXT'

  The one-line cautionary message about this deployment. This message is printed to the user if and only if the always-prompt flag causes the appearance of an urgent prompt.

• D_DPL_OS=( OS LIST )

  The value of this pseudo-variable defines the list of operating systems that the deployment supports. On non-supported OS’s, the deployment is ignored completely.

Below is an example of metadata in the head of a deployment script:

The following syntax limitations are imposed upon metadata:

• As mentioned above, the metadata must precede all other non-whitespace, non-commented lines of the deployment script.

• No more than one 'assignment' must be written per line, without line continuation.

• No Bash substitutions or comments are allowed.

• In keeping with the Bash syntax, no whitespace is allowed around the =.

• A pair of matching quotes around the value is allowed. Such pair of quotes is stripped in processing.

Deployment name and description

D_DPL_NAME=example
D_DPL_DESC='An example deployment'

Deployment priority

D_DPL_PRIORITY=777

Deployment flags

D_DPL_FLAGS=ci!89

Deployment warning

D_DPL_WARNING="Warning for 'urgent' prompts forced by a flag"

Deployment OS’s

# The deployment supports only the listed OS's:
  D_DPL_OS=( bsd macos )
  # or
  D_DPL_OS='debian fedora ubuntu'

# or

# The deployment supports all OS's except those listed:
  D_DPL_OS=( ! "linux" 'wsl' )
  # or
  D_DPL_OS="! cygwin msys solaris"

The return codes are the main vehicle for communicating to the framework the result of running a primary function.

The supported return codes have semantic meanings, which affect the human-readable output. In the case of the d_dpl_check function, the check code also determines whether the install and remove routines proceed with their task. Guidelines are provided for how to interpret the various check codes in the user-defined deployment code.

Finally, most of the extended check codes represent an unusual situation which causes the framework to unconditionally back off from the deployment, with an alert. This is in keeping with the framework’s non-interference policy. The --force option may be used to compel the framework.

check codes

install codes

remove codes

The add-statuses are the specially named global variables. The framework clears the add-statuses before running a primary function, and after running it — checks if the add-statuses contain (supported) values. The value assigned to an add-status changes the behavior of the framework.

An indicator variable (or simply an indicator) is a global variable that is populated by the framework at run-time with the intention of providing potentially useful information to the deployment code.

The indicator variables are read-only in spirit. However, due to practical limitations, they are not always protected from writing using the Bash’s readonly mechanism. Please, enjoy responsibly.

Manifests are processed in terms of lines. A simplest line represents an entry of some kind.

The whitespace rules are fairly permissive. Any amount of leading and trailing whitespace is allowed and ignored. Within an entry, the whitespace is preserved.

Whenever a line starts with an opening parenthesis ( and contains a closing one ), what’s between them is interpreted as a key-value pair. There may be more than one key-value per line. The key-values are used to qualify entries and provide additional information.

A key-value is separated into key and value by the first occurrence of the : symbol (colon).

Key-values may:

• occupy their own line;

• precede an entry.

Key-values that occupy their own line come into effect for the rest of the document, or until overridden. Key-values that precede an entry affect only that entry.

The two keys — os and flags — are universal to all types of manifests, and are described below. Particular kinds of manifests support additional keys.

Key-value os

(os: debian)          entry1    # Relevant only on Debian

(os: macos bsd)       entry2    # Relevant only on macOS or BSD

(os: ! linux wsl)     entry3    # Relevant everywhere except Linux or WSL

(os: all)             entry4    ## Keywords 'all'/'any' are reserved to denote
                                #. any OS. This is synonymous to empty list.

Key-value flags

(flags: i!0)  entry1    # Flags: i, !, 0

(flags: a)
              entry2    # Flags: a
(+b)
(flags: +c)   entry3    # Flags: a, b, c
              entry4    # Flags: a, b
(flags: d)    entry5    # Flags: d
              entry6    # Flags: a, b

The hash/pound symbol (#) comments out the rest of the line.

A line may be 'glued' to the next by terminating it with a backslash (\). Whitespace and comments are allowed to follow the backslash.

The escaping rules are as follows:

• To start an entry with a literal opening parenthesis (, prepend it with a backslash \.

  One and only one backslash is always removed from the left edge of an entry.

• To use a literal closing parenthesis ) within a key-value, prepend it with a backslash.

• To use a literal hash/pound symbol # anywhere, prepend it with a backslash.

• To end a line with a literal backslash \, double every literal backslash at the line’s right edge.

  An odd number of backslashes at the right edge of a line will be reduced to a single backslash and will result in line continuation.

The asset manifests are used to:

• Catalog the deployment’s assets.

• Copy the provided initial versions of assets into the asset directory.

• Automatically assemble queues from the asset paths.

The asset manifest is looked up at the path of the deployment file, with the .dpl.sh suffix exchanged for .dpl.mnf.

An asset manifest entry is a relative path to a file. (In regards to assets, the term 'file' includes directories.) Two kinds of relative paths are accepted: concrete paths and RegEx patterns. Leading and trailing slashes are always disregarded. The relative path is resolved from:

• the deployment directory (to locate the initial versions possibly provided with the deployment);

• the deployment’s asset directory (to locate the user’s current versions).

Processing of the asset manifests occurs:

• During the primary routines, immediately before sourcing the deployment script.

• After attaching a bundle.

The asset manifests follow the general manifest syntax, which provides the OS recognition and the flags.

What is being done for the catalogued assets is largely determined by their flags:

On top of the flags, the following key-values are recognized in asset manifests:

The RegEx patterns are interpreted by the find utility using the POSIX Extended Regular Expressions dialect. The provided pattern is inserted into a larger one, e.g.:

Consequently, the patterns should not include the ^ and $ meta-characters.

The order of entries in the asset manifest is guaranteed to correspond to the order of elements in the resulting asset arrays. However, the order of assets that match a single RegEx entry is not guaranteed.

The relative paths from a manifest are simply appended to their respective parent directories, so the paths like . or .. or ../.. will work.

Whenever the framework processes an existing asset manifest, it automatically clears and then populates two global arrays:

• D_QUEUE_ASSETS — absolute paths to the assets within the deployment’s asset directory.

• D_QUEUE_MAIN — for each absolute path in the previous array, this one will contain its relative version.

These arrays coincide with the arrays used by the queues, especially the link-queue and copy-queue variants. It makes sense, because the assets are the perfect candidates for sequential processing. The deployment is, of course, free to override these automatically populated arrays.

The Divinefiles are automatically picked up by the framework along with the other deployments. Divinefiles are processed in their merged entirety or not processed at all.

The Divinefiles are referred to with synonyms: divinefile, dfile, or df. As with all deployment names, these are case insensitive.

The deployment-style priorities and flags can be assigned to the individual packages within the Divinefiles. The packages are then intertwined with the regular deployments in a shared workflow.

The Divinefiles do not support the advanced features of the system package managers. For the more complex package installations — e.g., involving particular versions or special package manager options — the regular deployments should be used instead.

The Divinefiles follow the general manifest syntax.

Every Divinefile entry is a list of whitespace-separated package names. The keys flags and priority set the respective attributes for the packages. The priority works for packages in the same way as it does for the deployments.

The following flags are supported for packages.

Within a line, each vertical bar | starts an alt-list, which fully overrides the original list for a particular package manager. Within an alt-list, everything to the left of the first : symbol (colon) is read as the package manager’s name; everything to the right — as the alt-list of packages. The package manager’s name is matched against the $D__OS_PKGMGR variable.

To assemble a multitask deployment:

• Set the multitask determinant — an array named D_MLTSK_MAIN, each element of which single-handedly defines a task. The ordinal number of an array element is the task’s number, and the value of that element is the task’s name.

  D_MLTSK_MAIN=( task_one task_two )

  The multitask determinant must be populated before the first multitask helper (d__mltsk_check) is called.

  The determinant array must be continuous (uninterrupted).

• Implement the (optional) mini-primaries for the tasks, following the naming pattern (for the task named TASK):

  • d_TASK_check — the task-level equivalent of the d_dpl_check function.

  • d_TASK_install — the task-level equivalent of the d_dpl_install function.

  • d_TASK_remove — the task-level equivalent of the d_dpl_remove function.

• Call the multitask helper primaries as the last commands of the deployment’s primary functions, e.g.:

  d_dpl_check()   { d__mltsk_check;   }
  d_dpl_install() { d__mltsk_install; }
  d_dpl_remove()  { d__mltsk_remove;  }

The framework recognizes a set of specially named functions — hooks — that are called at particular junctions of processing a multitask deployment. The hooks have the power to alter the behavior of the multitask deployment via their return codes and add-statuses.

• Pre- and post- multitask hooks can do arbitrary work.

  • When the multitask check hook returns a non-zero code, the corresponding helper primary shuts down with the code 3 ('Irrelevant or invalid').

    • d_mltsk_pre_check — called before the checking of tasks starts.

    • d_mltsk_post_check — called after the checking of tasks concludes.

  • When the multitask install/remove hook returns a non-zero code, the corresponding helper primary shuts down with the code 2 ('Refused to install/remove').

    • d_mltsk_pre_install — called before (and if) the installation of tasks starts.

    • d_mltsk_post_install — called after the installation of tasks concludes.

    • d_mltsk_pre_remove — called before (and if) the removal of tasks starts.

    • d_mltsk_post_remove — called after the removal of tasks concludes.

• Pre- and post- task hooks can, too, do arbitrary work.

  • When the task check hook returns a non-zero code, the corresponding mini-primary shuts down with the code 3 ('Irrelevant or invalid').

    • d_TASK_pre_check — called before the checking of that task starts.

    • d_TASK_post_check — called after the checking of that task concludes.

  • When the task install/remove hook returns a non-zero code, the corresponding mini-primary shuts down with the code 2 ('Refused to install/remove').

    • d_TASK_pre_install — called before (and if) the installation of that task starts.

    • d_TASK_post_install — called after the installation of that task concludes.

    • d_TASK_pre_remove — called before (and if) the removal of that task starts.

    • d_TASK_post_remove — called after the removal of that task concludes.

The multitask deployments can take advantage of the deployment-level add-statuses. On top of that, the framework provides add-statuses that are specific to the multitask deployments.

The multitask deployments can take advantage of the deployment-level indicators. On top of that, the framework provides indicators that are specific to the multitask deployments.

To assemble a generic queue within a deployment (or a task):

• Set the queue determinant — an array named D_QUEUE_MAIN, each element of which single-handedly defines a queue item. The ordinal number of an array element is the item’s number, and the value of that element is the item’s name.

  D_QUEUE_MAIN=( item_one item_two )

  The queue determinant must be populated before the first queue helper (d__queue_check) is called. The queue array may be automatically populated via the queue or asset manifests.

  The determinant array must be continuoue (uninterrupted).

• Implement the (optional) mini-primaries for the queue items:

  • d_item_check — the queue item equivalent of the d_dpl_check function.

  • d_item_install — the queue item equivalent of the d_dpl_install function.

  • d_item_remove — the queue item equivalent of the d_dpl_remove function.

• Call the queue helper primaries as the last commands of the deployment’s (or task’s) primary functions, e.g.:

  d_dpl_check()   { d__queue_check;   }
  d_dpl_install() { d__queue_install; }
  d_dpl_remove()  { d__queue_remove;  }

The queue items, whatever they are, may be separated from the deployment logic into their own file, the queue manifest. The framework detects the asset manifest and automatically assembles the queue determinant from it.

The queue manifest is looked up, by default, at the path of the deployment file, with the .dpl.sh suffix exchanged for .dpl.que. Unlike with the asset manifests, the deployment is free to customize the location of the queue manifest via an add-status.

The queue manifests follow the general manifest syntax, which provides the OS recognition. The manifest flags are not used. On top of that, a queue splitting mechanism is supported:

The framework recognizes a set of specially named functions — hooks — that are called at particular junctions of processing a queue. The hooks have the power to alter the behavior of the queue via their return codes and add-statuses.

• Pre- and post- queue hooks can do arbitrary work.

  • When the queue check hook returns a non-zero code, the corresponding helper primary shuts down with the code 3 ('Irrelevant or invalid').

    • d_queue_pre_check — called before the checking of items starts.

    • d_queue_post_check — called after the checking of items concludes.

  • When the queue install/remove hook returns a non-zero code, the corresponding helper primary shuts down with the code 2 ('Refused to install/remove').

    • d_queue_pre_install — called before (and if) the installation of items starts.

    • d_queue_post_install — called after the installation of items concludes.

    • d_queue_pre_remove — called before (and if) the removal of items starts.

    • d_queue_post_remove — called after the removal of items concludes.

• Pre- and post- item hooks can, too, do arbitrary work.

  • When the item check hook returns a non-zero code, the corresponding mini-primary shuts down with the code 3 ('Irrelevant or invalid').

    • d_item_pre_check — called before the checking of an item starts.

    • d_item_post_check — called after the checking of an item concludes.

  • When the item install/remove hook returns a non-zero code, the corresponding mini-primary shuts down with the code 2 ('Refused to install/remove').

    • d_item_pre_install — called before (and if) the installation of an item starts.

    • d_item_post_install — called after the installation of an item concludes.

    • d_item_pre_remove — called before (and if) the removal of an item starts.

    • d_item_post_remove — called after the removal of an item concludes.

The queues can take advantage of the deployment-level add-statuses. On top of that, the framework provides add-statuses that are specific to the queues.

The queues can take advantage of the deployment-level indicators. On top of that, the framework provides indicators that are specific to the queues.

The queue helpers can be employed more than once per deployment. When that happens, all types of queues (generic and the various specialized types) share the same internal mechanism and the same determinant, D_QUEUE_MAIN. Consequently, when a deployment contains multiple queues, the queue must be split into queue sections.

Queue sections are delimited by the ordinal number of their first elements in the queue array (determinant). Such delimiters are called the queue splits. A section spans from its split until the split of the next section (the latter not inclusive), or until the end of the queue array. The first section always implicitly starts at the first element of the queue array. So, the total number of queue sections is the number of splits plus one. (The word 'first' is used for readability; the underlying Bash numberings start at 0.)

There are two ways to split a queue:

• In the deployment code, call the d__queue_split function:

  D_QUEUE_MAIN=( elem0-0 elem0-1 elem0-2 )  # Initialize with first section
  
  d__queue_split  ## Without arguments, splits at the current right edge of the
                  #. queue array (in this example - position 3)
  
  D_QUEUE_MAIN+=( elem1-0 elem1-1 elem2-0 elem2-1 )  # Append two more sections
  
  d__queue_split 5  ## Manual split after the fact, at position 5, 'elem2-0'

• In the asset and queue manifests, the automatically populated queue array can be split by including the key-value (queue: split) at the desired split position.

The queue determinant may be put together incrementally, but a section of it must be fully assembled by the time its first helper primary is called.

Whenever a queue section uses multiple arrays to store relevant data (which is true, for instance, for all specialized queues), a care must be taken to ensure that all arrays use the same indices for the same queue items.

It is crucial to understand, that the framework unsets (deletes) the queue’s mini-primaries, add-statuses, and hooks as soon as the current queue section has used them fully. Each subsequent section needs to define and implement its own.

Regardless of whether the deployment employs the queues, the framework automatically populates the queue determinant (and some accompanying arrays) whenever a suitable manifest is encountered.

Such auto-queues are built at two points in processing of a deployment. The order is significant here, because the queues supersede each other.

1. Before the deployment script is sourced, an auto-queue is built from the deployment’s asset manifest:

   • D_QUEUE_MAIN — populated with the relative paths to the assets.

   • D_QUEUE_ASSETS — populated with the absolute versions thereof. This array is used by the copy-queue and the link-queue variations.

   This kind of auto-queue can be handily complemented with the auto-targeting.

2. Immediately after the deployment script is sourced (and before any deployment functions are called), an auto-queue is built from the deployment’s queue manifest:

   • D_QUEUE_MAIN — populated with the manifest entries.

An auto-queue is only built if the corresponding manifest exists. Both types of auto-queues support splitting the queue (via the manifest syntax).

Queue auto-targeting

D_QUEUE_MAIN=( 'rel/path0' 'rel/path1' 'rel/path2' )  # Initialize the queue

d__queue_target '/target/dir'  # Without options, whole queue is auto-targeted

## This effectively populates the target array as such:
#>  D_QUEUE_TARGETS=( \
#>    /target/dir/rel/path0 \
#>    /target/dir/rel/path1 \
#>    /target/dir/rel/path2 \
#>  )
#

d__queue_target [-s|--section SECTNUM] [--] TARGET_DIR

The copy-queue takes a list of asset paths, a list of destination paths, and sequentially copies the former onto the latter. No overwriting is done, although this can be influenced. The stashing system is used to track the installations of the copy-queue.

Setting up a copy-queue

# ~/.grail/dpls/copy-queue-example.dpl.sh

d_dpl_check()   { assemble_queue; d__copy_queue_check;   }
d_dpl_install() {                 d__copy_queue_install; }
d_dpl_remove()  {                 d__copy_queue_remove;  }

assemble_queue()
{
  D_QUEUE_MAIN=( '.hushlogin' )
  D_QUEUE_ASSETS=( "$D__DPL_ASSET_DIR/.hushlogin" )
  D_QUEUE_TARGETS=( "$HOME/.hushlogin" )
}

Copy-queue hooks, add-statuses, and indicators

The link-queue takes a list of asset paths, a list of destination paths, and sequentially creates symlinks at the latter, pointing to the former. Any pre-existing files at the symlink locations are backed up. The stashing system is used to track the installations of the link-queue.

Setting up a link-queue

# ~/.grail/dpls/link-queue-example.dpl.sh

d_dpl_check()   { assemble_queue; d__link_queue_check;   }
d_dpl_install() {                 d__link_queue_install; }
d_dpl_remove()  {                 d__link_queue_remove;  }

assemble_queue()
{
  D_QUEUE_MAIN=( '.bashrc' )
  D_QUEUE_ASSETS=( "$D__DPL_ASSET_DIR/.bashrc" )
  D_QUEUE_TARGETS=( "$HOME/.bashrc" )
}

Link-queue hooks, add-statuses, and indicators

The Github-queue takes a list of Github repository handles (username/repository), a list of destination paths, and sequentially clones/downloads the former into the latter. The stashing system is used to track the installations of the Github-queue.

Setting up a Github-queue

# ~/.grail/dpls/github-queue-example.dpl.sh

d_dpl_check()   { assemble_queue; d__gh_queue_check;   }
d_dpl_install() {                 d__gh_queue_install; }
d_dpl_remove()  {                 d__gh_queue_remove;  }

assemble_queue()
{
  D_QUEUE_MAIN=( 'ohmyzsh/ohmyzsh' )
  D_QUEUE_TARGETS=( "$HOME/.oh-my-zsh" )
}

Github-queue hooks, add-statuses, and indicators

Divine.dotfiles uses a system of prefixes to gradually separate the framework’s inner workings.

• The single-underscore prefixes are for entities to be implemented by a deployment:

  • D_NAME — the variables to be assigned, e.g., the metadata and the add-statuses.

  • d_name — the functions to be implemented, e.g., the primary functions.

• The double-underscore prefixes are for entities to be accessed by a deployment:

  • D__NAME — the variables to be read, e.g., the indicators.

  • d__name — the functions to be called, e.g., the d__stash function.

• The triple-underscore prefixes are for entities that are strictly internal:

  • d___name — the functions that the framework uses for logic encapsulation.

To stay on the safe side, the deployment code needs to stay away from identifiers that start with the letter d/D followed by an underscore, unless a framework mechanism is being employed.

The Divine workflow is the recommended way to organize Bash code within deployments. The framework provides a set of functions that facilitate breaking down Bash code into meaningful blocks. The goal of the workflow system is to both annotate the code and automatically provide useful debug output.

Central to the idea of the Divine workflow is the concept of workflow context. The workflow context is a stack (similar to the function call stack) that at any moment contains the hierarchy of tasks currently being performed. The context stack can be visualized like this:

The context stack starts at the root and grows down to arbitrary depth. Context items are pushed and popped from the bottom. Notches — represented by the three hyphens (---) in the illustration — delimit the logical stratas.

With the idea of context in mind, the Divine workflow boils down to the following principles:

• The logic should be encapsulated in functions.

• The workflow context tree should be grown by calling the d__context function:

  • d__context notch — to place a notch.

  • d__context push — to push a workflow item onto the stack.

• Whenever a context branch needs to fail:

  • Critical commands could be wrapped in the d__cmd, d__pipe, or d__require calls.

  • 'Manual' failures should be orchestrated via the d__fail function.

• To interact with the user along the way:

  • Non-failure alerts should be delivered via the d__notify function.

  • Prompts could be initiated via the d__prompt function.

• To finalize successful runs:

  • d__context pop — to pop a workflow item from the stack.

  • d__context lop — to slash the context stack up to and including the latest notch.

If a push is prepended to every logical unit of code, and then a matching pop is appended at the end, a useful pattern of breadcrumbs arises in the debug output. The Divine workflow functions (d__notify, d__prompt, d__fail, d__cmd, d__pipe, d__require) may include the state of the context stack in their output.

With the default verbosity level, the code above produces no output when successful. If something goes wrong in the critical task, a message similar to the following will be printed:

Function d__context

d__context [-!dlnqsvx] [-t TITLE] [--] push|pop|notch|lop DESCRIPTION|[DESCRIPTION]

# Pushing an item
==> Start: Description of the context item

# Popping an item
==> End: Description of the context item

# Making a notch
==> Notched: At position X

# Removing a notch
==> De-notched: At position X

Function d__notify

d__notify [-!1cdhlnqsuvx] [-t TITLE] [--] [DESCRIPTION...]

==> TITLE

==> TITLE: DESCRIPTION-0
    DESCRIPTION-1
    ...
    Context: CONTEXT-0
             CONTEXT-1
             ...

Function d__prompt

d__prompt [-!1bchknqsvxy] [-p PROMPT] [-a ANSWER] [-t TITLE] [--] [DESCRIPTION...]

PROMPT KEYS

==> TITLE: DESCRIPTION-0
    DESCRIPTION-1
    ...
    Context: CONTEXT-0
             CONTEXT-1
             ...
    PROMPT KEYS

Function d__fail

d__fail [-n] [-t TITLE] [--] [DESCRIPTION...]

==> TITLE

==> TITLE: DESCRIPTION-0
    DESCRIPTION-1
    ...
    Context: CONTEXT-0
             CONTEXT-1
             ...

Function d__cmd

d__cmd [options] [----] CMD...