Skip to content

Latest commit

 

History

History
175 lines (134 loc) · 4.73 KB

dotsetup.1.adoc

File metadata and controls

175 lines (134 loc) · 4.73 KB

dotsetup(1) Manual Page

Name

dotsetup - YAML config based backup utility

Synopsis

dotsetup [-h|--help] [-c|--config CONFIG] [-l|--list] [-v|--version] [--clean] [--log-level LOG_LEVEL] [APP…​]

Description

Usually people maintain backup and setup scripts along with their dotfiles. But these scripts always contain a lot of repeat codes, and writing them is not fun! dotbackup and dotsetup are here to help.

With these two tools, you only need to write a simple configuration and they will know how to back up and set up your dotfiles. See the CONFIGURATION section for the configuration definition.

When you invoke dotbackup, it copies each application’s files to the backup_dir (if no app provided, all application’s files will be copied). And dotsetup does the opposite. Backup file’s relative path to the backup_dir is the same as the original file’s relative path to the home directory, so dotsetup knows how to copy them back.

Options

-h, --help

Show help message and exit.

-c, --config=CONFIG

Set configuration file path (default: ~/.config/dotbackup/dotbackup.yml). Configuration files under ~/.config/dotbackup can also be specified by their basenames, e.g., ~/.config/dotbackup/config.yml can be specified by config. See CONFIGURATION section for configuration definition.

-l, --list

List configured application and exit.

-v, --version

Print the version information and exit.

--clean

Do clean setup, i.e., delete old configuration files before setup.

--log-level LOG_LEVEL

Set the log level, LOG_LEVEL may be one of DEBUG, INFO, WARNING, ERROR, CRITICAL. The default is INFO.

Configuration

The default configuration file path is ~/.config/dotbackup/dotbackup.yml. The configuration file uses YAML syntax, following are the configuration keyword definitions.

backup_dir

A string. The directory where backup files are stored.

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>.files

A list of path strings. The files to be backed up of the application <app>, <app> can be any string. File paths MUST be relative to the home directory 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 may be like this:

pre_backup
apps.app1.pre_backup
copy apps.app1.files
apps.app1.post_backup
apps.app2.pre_backup
copy apps.app2.files
apps.app2.post_backup
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 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]

Resources

See also

dotbackup(1)