Examples

To understand how a SALVE execution runs, here we present several examples and describe how an execution with them runs.

All examples are evaluated with the following directory structure:

root.manifest
manifests
|-- bash.manifest
|-- vim.manifest
`-- zsh.manifest
files
|-- bash
|   `-- bashrc
|-- zsh
|   |-- zsh_dircolors
|   |-- zsh_git_aliases
|   |-- zshrc
|   `-- zshrc.zni
`-- vim
    |-- solarized.vim
    `-- vimrc

Example 1: bash Manifest

Consider the following manifest that handles a single bashrc file. This is about as simple as a manifest can be.

file {
    source  "files/bash/bashrc"
    target  "$HOME/.bashrc"
}

at manifests/bash.manifest.

bash Manifest Expanded

When run via salve deploy -m manifests/bash.manifest, this manifest expands with defaults settings to

file {
    source      "files/bash/bashrc"
    target      "$HOME/.bashrc"
    action      copy
    mode        600
    user        "$USER"
    group       "$SALVE_USER_PRIMARY_GROUP"
}

This specifies that the file at files/bash/bashrc, should be copied to $HOME/.bashrc. Its mode should be set to 600, and if running as root, the user and group should be set to the invoking user and that user's primary group (inspecting $SUDO_USER to deduce who that user is). If there is an existing file at $HOME/.bashrc, SALVE will back it up before replacing it.

Example 2: zsh Manifest

Consider the following manifest that handles zsh configuration, stored in manifests/zsh.manifest.

file {
    source  "files/zsh/zshrc"
    target  "$HOME/.zshrc"
}

file {
    source  "files/zsh/zshrc.zni"
    target  "$HOME/.zshrc.zni"
}

file {
    source  "files/zsh/zsh_git_aliases"
    target  "$HOME/.zsh_git_aliases"
}

file {
    source  "files/zsh/zsh_dircolors"
    target  "$HOME/.zsh_dircolors"
}

zsh Manifest: First Block

When run via salve deploy -m manifests/zsh.manifest, this manifest first specifies

file {
    source  "files/zsh/zshrc"
    target  "$HOME/.zshrc"
}

which expands with the defaults to

file {
    source      "files/zsh/zshrc"
    target      "$HOME/.zshrc"
    action      copy
    mode        600
    user        "$USER"
    group       "$SALVE_USER_PRIMARY_GROUP"
}

As with the bash manifest, this specifies that the file at files/zsh/zshrc, should be copied to $HOME/.zshrc.

zsh Manifest: All Blocks

As a more complete view, a fully expanded manifest is

file {
    source      "files/zsh/zshrc"
    target      "$HOME/.zshrc"
    action      copy
    mode        600
    user        "$USER"
    group       "$SALVE_USER_PRIMARY_GROUP"
}

file {
    source      "files/zsh/zshrc.zni"
    target      "$HOME/.zshrc.zni"
    action      copy
    mode        600
    user        "$USER"
    group       "$SALVE_USER_PRIMARY_GROUP"
}

file {
    source      "files/zsh/zsh_git_aliases"
    target      "$HOME/.zsh_git_aliases"
    action      copy
    mode        600
    user        "$USER"
    group       "$SALVE_USER_PRIMARY_GROUP"
}

file {
    source      "files/zsh/zsh_dircolors"
    target      "$HOME/.zsh_dircolors"
    action      copy
    mode        600
    user        "$USER"
    group       "$SALVE_USER_PRIMARY_GROUP"
}

Example 3: vim Manifest

The following manifest handles vim configuration, and includes a directory action. It is kept under the name of manifest/vim.manifest.

directory {
    target  "$HOME/.vim/colors"
    action  create
}

file {
    source  "files/vim/vimrc"
    target  "$HOME/.vimrc"
}

file {
    source  "files/vim/solarized.vim"
    target  "$HOME/.vim/colors/solarized.vim"
}

vim Manifest: First Block

When run via salve deploy -m manifest/vim.manifest, this manifest first specifies

directory {
    target  "$HOME/.vim/colors"
    action  create
}

which expands with the defaults to

directory {
    target      "$HOME/.vim/colors"
    action      create
    mode        755
    user        "$USER"
    group       "$SALVE_USER_PRIMARY_GROUP"
}

This specifies that a directory at $HOME/.vim/colors should be created if it does not already exist, as it would be by the shell command mkdir -p. Its mode should be set to 755, and if running as root, the user and group should be set. 755 is recommended for directories when possible, as it is the least likely value to create error conditions later in the SALVE run. With this action, there is no backup because the operations performed are necessarily nondestructive.

vim Manifest: All Blocks

As a more complete view, a fully expanded manifest is

directory {
    action      create
    target      "$HOME/.vim/colors"
    mode        755
    user        "$USER"
    group       "$SALVE_USER_PRIMARY_GROUP"
}

file {
    action      copy
    source      "files/vim/vimrc"
    target      "$HOME/.vimrc"
    mode        600
    user        "$USER"
    group       "$SALVE_USER_PRIMARY_GROUP"
}

file {
    action      copy
    source      "files/vim/solarized.vim"
    target      "$HOME/.vim/colors/solarized.vim"
    mode        600
    user        "$USER"
    group       "$SALVE_USER_PRIMARY_GROUP"
}

Note that the file[mode] and directory[mode] are distinct, and that the specified directory action overrides the default action, copy.