DOTBACKUP(5)

NAME

dotbackup - configuration file definition for dotbackup(1)

DEFINITION

Configuration files use YAML syntax, unknown entries are ignored.

dotfile_root
    A string. The root directory of dotfiles. dotbackup use this to compute the relative paths to store dotfile backups. The default is the home directory.

backup_dir
    Required. A string. The directory where backup files are stored.

backup_dir_linux
    A string. The directory where backup files are stored on Linux systems.

backup_dir_macos
    A string. The directory where backup files are stored on macOS.

backup_dir_windows
    A string. The directory where backup files are stored on Windows.

clean
    A boolean. Whether to delete files in destination path before backup and setup. The default is `false`. Option --clean override this configuration.

ignore
    A list of glob strings. The global ignored file patterns. Files that matches one of these patterns will be ignored. But files that are directly specified in apps.<app>.files are not ignored.

apps.<app>.backup_dir
    A string. The directory where backup files are stored, only for this app.

apps.<app>.backup_dir_linux
    A string. The directory where backup files are stored, only for this app on Linux systems.

apps.<app>.backup_dir_macos
    A string. The directory where backup files are stored, only for this app on macOS.

apps.<app>.backup_dir_windows
    A string. The directory where backup files are stored, only for this app on Windows.

apps.<app>.files
    A list of path strings. The files to be backed up of the application <app> for all systems, <app> can be any string. File paths MUST be under dotfile_root due to implementation. You can use HOOKS to manipulate other files.

apps.<app>.files_linux
    A list of path strings. The files to be backed up of the application <app> only for Linux systems, <app> can be any string. File paths MUST be under dotfile_root due to implementation. You can use HOOKS to manipulate other files.

apps.<app>.files_macos
    A list of path strings. The files to be backed up of the application <app> only for macOS, <app> can be any string. File paths MUST be under dotfile_root due to implementation. You can use HOOKS to manipulate other files.

apps.<app>.files_windows
    A list of path strings. The files to be backed up of the application <app> only for Windows, <app> can be any string. File paths MUST be under dotfile_root due to implementation. You can use HOOKS to manipulate other files.

apps.<app>.ignore
    A list of glob strings. The application level ignored file patterns. Files that matches one of these patterns will be ignored when back up and set up <app>. But files that are directly specified in apps.<app>.files are not ignored.

apps.<app>.<pre_backup|post_backup|pre_setup|post_setup>
    A list of script strings. The application level custom hooks, <app> can be any string. See HOOKS and EXAMPLES for details.

<pre_backup|post_backup|pre_setup|post_setup>
    A list of script strings. The global custom hooks. See HOOKS and EXAMPLES for details.

HOOKS

Technically, hooks are just shell scripts to be executed by `sh -s`. They can be divide into backup hooks and setup hooks. The execution order is indicated by their names. For example, the execution order of backup hooks is like:

    pre_backup
    apps.app1
    	apps.app1.pre_backup
    	copy apps.app1.files
    	apps.app1.post_backup
    apps.app2
    ...
    post_backup

And in hooks, you can use the environment variable BACKUP_DIR which is set to backup_dir. So you can use hooks to do things beyond copying files, e.g., file post-processing.

EXAMPLES

First of all, dotbackup can back up itself:

    backup_dir: ~/backup
    apps:
      dotbackup:
        files: [~/.config/dotbackup/dotbackup.yml]

A configuration back up Vim and Neovim:

    backup_dir: ~/backup
    apps:
      vim:
        files: [~/.vimrc]
      nvim:
        files:
          - ~/.config/nvim/init.lua
          - ~/.config/nvim/lua

A configuration which use hooks to generate timestamp and make Git commit:

    backup_dir: ~/backup
    apps:
      vim:
        files: [~/.vimrc]
      nvim:
        files:
          - ~/.config/nvim/init.lua
          - ~/.config/nvim/lua
    post_backup:
      - date > "$BACKUP_DIR/timestamp"
      - |
        set -e
        cd $BACKUP_DIR
        git commit -am "backup of $(date)"
        git push

A configuration which ignore some files:

    backup_dir: ~/backup
    apps:
      nvim:
        files: [~/.config/nvim]
        ignore: [lazy-lock.json]
    ignore: [.git]