Skip to content

Configuration

Jump to bottom
Chris Purcell edited this page Feb 7, 2026 · 1 revision

Configuration Reference

DFBU uses YAML configuration files split across three distinct files for clarity and separation of concerns.

Configuration Files Overview

File Purpose Location Scope
settings.yaml Backup paths and options Config directory Global settings
dotfiles.yaml Dotfile library definitions Config directory Backup inventory
session.yaml Temporary exclusions Config directory Session state
profiles.yaml Named backup profiles Config directory Profile storage

Configuration Locations

AppImage Installation:

  • ~/.config/dfbu/

Source Installation:

  • DFBU/data/ (development default)
  • Can be changed to ~/.config/dfbu/

settings.yaml

Global application settings, backup paths, and operational options.

File Structure

paths:
  mirror_dir: ~/backups/mirror
  archive_dir: ~/backups/archives
  restore_backup_dir: ~/.local/share/dfbu/restore-backups

options:
  mirror: true
  archive: true
  hostname_subdir: true
  date_subdir: true
  archive_format: tar.gz
  archive_compression_level: 5
  rotate_archives: true
  max_archives: 5
  pre_restore_backup: true
  max_restore_backups: 5
  verify_after_backup: true
  hash_verification: true
  size_check_enabled: true
  size_warning_threshold_mb: 10
  size_alert_threshold_mb: 100
  size_critical_threshold_mb: 1024

paths Section

mirror_dir

Type: String (path) Description: Destination directory for mirror backups Default: ~/backups/mirror Example: ~/GitHub/dotfiles

Creates readable directory structure preserving original file layout.

archive_dir

Type: String (path) Description: Destination directory for compressed archives Default: ~/backups/archives Example: ~/pCloudDrive/Backups/Dotfiles

Stores .tar.gz compressed backup archives.

restore_backup_dir

Type: String (path) Description: Directory for pre-restore safety backups Default: ~/.local/share/dfbu/restore-backups

DFBU creates timestamped backups here before restoring files.

options Section

Backup Mode Options

mirror Type: Boolean Default: true Description: Enable mirror backup mode

When enabled, creates readable directory structure backups.

archive Type: Boolean Default: true Description: Enable archive backup mode

When enabled, creates compressed .tar.gz archives.

Note: Both can be enabled simultaneously for dual-mode backups.

Organization Options

hostname_subdir Type: Boolean Default: true Description: Create subdirectory named after hostname

Output structure with hostname_subdir: true:

~/backups/mirror/
└── my-laptop/
    ├── bash/
    ├── vim/
    └── config/

Output structure with hostname_subdir: false:

~/backups/mirror/
├── bash/
├── vim/
└── config/

date_subdir Type: Boolean Default: true Description: Create dated subdirectories for archives

With date_subdir: true:

~/backups/archives/my-laptop/
├── 2026-02-07/
│   └── backup-083015.tar.gz
└── 2026-02-06/
    └── backup-210342.tar.gz

With date_subdir: false:

~/backups/archives/my-laptop/
├── backup-20260207-083015.tar.gz
└── backup-20260206-210342.tar.gz

Archive Options

archive_format Type: String Default: tar.gz Options: tar.gz, tar (future: zip, tar.bz2, tar.xz)

Archive compression format.

archive_compression_level Type: Integer (1-9) Default: 5 Description: gzip compression level

  • 1: Fastest compression, larger files
  • 5: Balanced compression and speed
  • 9: Maximum compression, slower

rotate_archives Type: Boolean Default: true Description: Enable automatic archive rotation

When enabled, old archives are deleted when max_archives limit is exceeded.

max_archives Type: Integer Default: 5 Description: Maximum number of archives to retain

Oldest archives are deleted first when limit is reached.

Restore Safety Options

pre_restore_backup Type: Boolean Default: true Description: Create safety backup before restoration

Strongly recommended. Backs up existing files before overwriting.

max_restore_backups Type: Integer Default: 5 Description: Maximum number of restore backups to retain

Automatic cleanup when limit is exceeded.

Verification Options

verify_after_backup Type: Boolean Default: true Description: Verify backup integrity after completion

Performs existence and size checks on backed-up files.

hash_verification Type: Boolean Default: true Description: Enable SHA-256 hash verification

More thorough verification but slower. Recommended for critical backups.

Size Analysis Options

size_check_enabled Type: Boolean Default: true Description: Enable pre-backup size analysis

Warns about large files before backup operation.

size_warning_threshold_mb Type: Integer Default: 10 Description: Warning threshold in megabytes (yellow indicator)

size_alert_threshold_mb Type: Integer Default: 100 Description: Alert threshold in megabytes (orange indicator)

size_critical_threshold_mb Type: Integer Default: 1024 Description: Critical threshold in megabytes (red indicator)

dotfiles.yaml

Dotfile library defining all configuration files and directories to backup.

File Structure

# Application Name:
#   description: Brief description
#   path: single/path        # For single file/directory
#   paths:                   # For multiple paths
#     - /path/one
#     - /path/two
#   tags: comma, separated, tags  # Optional

Bash:
  description: Bash shell startup configuration and history
  paths:
    - ~/.bashrc
    - ~/.bash_profile
    - ~/.bash_aliases
  tags: shell, terminal

Vim:
  description: Vim text editor configuration
  path: ~/.vimrc
  tags: editor, terminal

Alacritty:
  description: Alacritty terminal emulator configuration
  paths:
    - ~/.config/alacritty/alacritty.yml
    - ~/.config/alacritty/alacritty.toml
  tags: terminal, gui

Dotfile Entry Fields

Application Name (Key)

Required: Yes Type: String Description: Unique identifier for the dotfile entry

Used for display, filtering, and reference. Should be descriptive.

description

Required: Yes Type: String Description: Human-readable description of the configuration

Displayed in the UI to help identify dotfiles.

path / paths

Required: Yes (one of them) Type: String (path) or List of strings Description: File or directory paths to backup

Use path for single item:

Vim:
  description: Vim configuration
  path: ~/.vimrc

Use paths for multiple items:

Bash:
  description: Bash configuration
  paths:
    - ~/.bashrc
    - ~/.bash_profile

Path Expansion:

  • ~ expands to user home directory
  • Environment variables supported: $HOME, $USER, etc.
  • Absolute paths: /etc/fstab
  • Relative paths: ./local-config

tags

Required: No Type: String (comma-separated) Description: Classification tags for filtering and organization

Examples:

  • shell, terminal
  • editor, gui
  • dev, python
  • browser, privacy

Tag Filtering: Use filter input in Backup tab to search by tags.

Example Dotfile Entries

Shell Configurations

Bash:
  description: Bash shell startup configuration and history
  paths:
    - ~/.bashrc
    - ~/.bash_profile
    - ~/.bash_aliases
  tags: shell, terminal

Zsh:
  description: Zsh shell configuration
  paths:
    - ~/.zshrc
    - ~/.zprofile
  tags: shell, terminal

Fish:
  description: Fish shell configuration
  paths:
    - ~/.config/fish/config.fish
    - ~/.config/fish/functions
  tags: shell, terminal

Editor Configurations

Vim:
  description: Vim text editor configuration
  path: ~/.vimrc
  tags: editor, terminal

Neovim:
  description: Neovim editor configuration
  path: ~/.config/nvim
  tags: editor, terminal

VS Code:
  description: Visual Studio Code settings and extensions
  paths:
    - ~/.config/Code/User/settings.json
    - ~/.config/Code/User/keybindings.json
  tags: editor, gui, ide

Application Configurations

Git:
  description: Git version control configuration
  paths:
    - ~/.gitconfig
    - ~/.gitignore_global
  tags: dev, vcs

SSH:
  description: SSH client configuration (not private keys)
  paths:
    - ~/.ssh/config
    - ~/.ssh/known_hosts
  tags: network, security

Firefox:
  description: Firefox browser profiles
  path: ~/.mozilla/firefox
  tags: browser, gui

session.yaml

Temporary session state and exclusions.

File Structure

excluded:
  - Firefox
  - Steam
  - Chrome

excluded

Type: List of strings Description: Dotfile names to exclude from backup operations

Characteristics:

  • Temporary exclusions for current session
  • Persists across application restarts
  • Independent of dotfile library
  • Can be cleared via "Clear Exclusions" button

Use Cases:

  • Temporarily skip large directories
  • Exclude problematic files during testing
  • Selective backups for specific purposes

profiles.yaml

Named backup profile configurations (v1.1.0+).

File Structure

profiles:
  Work:
    description: Work-related configurations only
    excluded:
      - Steam
      - Firefox Personal
      - Music Players
    options:
      mirror: true
      archive: true
      compression_level: 9
      verify_after_backup: true

  Personal:
    description: Personal dotfiles and settings
    excluded:
      - Work VPN
      - Corporate Tools
    options:
      mirror: true
      archive: false

  Minimal:
    description: Essential files only
    excluded:
      - Firefox
      - Steam
      - VS Code
      - Chrome
    options:
      mirror: true
      archive: true
      compression_level: 5

Profile Fields

Profile Name (Key)

Required: Yes Type: String Description: Unique profile identifier

description

Required: No Type: String Description: Profile purpose description

excluded

Required: No Type: List of strings Description: Dotfiles to exclude in this profile

options

Required: No Type: Dictionary Description: Option overrides for this profile

Available overrides:

  • All options from settings.yaml
  • Profile-specific values override globals
  • Unspecified options use global defaults

.dfbuignore

Gitignore-style exclusion patterns for size analysis (v1.0.0+).

File Structure

# Cache directories
__pycache__/
*.pyc
.cache/
**/cache/

# Build artifacts
*.o
*.so
build/
dist/

# Logs and temporary files
*.log
*.tmp
logs/
*.swp
*.swo

# Dependencies
node_modules/
vendor/
.venv/

# IDE and editor files
.vscode/
.idea/
*.code-workspace

Pattern Syntax

Wildcards:

  • *: Matches any characters except /
  • **: Matches any characters including /
  • ?: Matches single character

Examples:

*.log          # All .log files in current directory
**/*.log       # All .log files in any subdirectory
logs/          # Entire logs directory
cache*/        # Directories starting with "cache"
.DS_Store      # macOS metadata files

Negation:

# Ignore all logs except important.log
*.log
!important.log

Comments:

# This is a comment
# Empty lines are ignored

*.tmp          # Inline comments supported

Default .dfbuignore

DFBU includes a default .dfbuignore with common exclusions:

  • Python cache (__pycache__, *.pyc)
  • Node.js modules (node_modules/)
  • Build directories (build/, dist/)
  • Cache directories (.cache/, cache/)
  • Log files (*.log, logs/)
  • Temporary files (*.tmp, *.swp)

Location: ~/.config/dfbu/.dfbuignore or DFBU/data/.dfbuignore

Configuration Management

Editing Configuration

Via GUI:

  1. Edit Config Button: Opens dotfiles.yaml in system editor
  2. Configuration Tab: Modify settings via GUI controls
  3. Profile Dialog: Create/edit profiles

Manual Editing:

# Edit settings
nano ~/.config/dfbu/settings.yaml

# Edit dotfile library
nano ~/.config/dfbu/dotfiles.yaml

# Edit exclusions
nano ~/.config/dfbu/session.yaml

Validating Configuration

Via GUI:

  • Click "Validate Config" button in Configuration tab
  • Reports YAML syntax errors and missing required fields

Via Command Line:

# Check YAML syntax
python3 -c "import yaml; yaml.safe_load(open('settings.yaml'))"

Exporting Configuration

Via GUI:

  • Click "Export Config" button
  • Choose destination directory
  • Exports settings.yaml and dotfiles.yaml

Manual Export:

# Backup configuration
cp ~/.config/dfbu/*.yaml ~/config-backup/

Importing Configuration

Manual Import:

# Restore configuration
cp ~/config-backup/*.yaml ~/.config/dfbu/

Reload in GUI:

  • Restart DFBU or click "Load Config" button

Configuration Best Practices

Backup Path Selection

Mirror Directory:

  • Use fast, local storage for frequent access
  • Consider version control integration (Git)
  • Adequate space for full directory structures

Archive Directory:

  • Cloud storage or external drives acceptable
  • Compression saves significant space
  • Network-mounted storage supported

Restore Backup Directory:

  • Fast local storage recommended
  • Automatic cleanup manages space

Compression Level Selection

Level Speed Compression Use Case
1-3 Fast Low Frequent backups, SSD storage
4-6 Balanced Medium General use, recommended
7-9 Slow High Archival, limited storage

Verification Strategy

Enable verification when:

  • Critical configuration backups
  • First-time backup setup
  • After system changes
  • Network/cloud destinations

Disable hash verification when:

  • Very large backups (>1GB)
  • Frequent automated backups
  • Performance is critical

Size Threshold Configuration

Adjust thresholds based on:

  • Available storage space
  • Typical dotfile sizes
  • Network bandwidth (for cloud backups)

Recommended thresholds:

  • Warning: 10 MB (alerts to unexpected large files)
  • Alert: 100 MB (requires attention)
  • Critical: 1 GB (may indicate misconfiguration)

Profile Usage

Create profiles for:

  • Different machines (work laptop, home desktop)
  • Different backup scenarios (minimal, full, sync)
  • Testing and production configurations
  • Scheduled vs. manual backups

Navigation: Home | Features | User Guide | Installation

Clone this wiki locally