Skip to content

User Guide

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

User Guide

Comprehensive step-by-step guide to using DFBU for dotfile backup and restoration.

Getting Started

First Launch

  1. Launch DFBU:

    # AppImage
./DFBU-x86_64.AppImage

# Source installation
python DFBU/dfbu_gui.py

  2. Initial Configuration: DFBU creates default configuration files on first launch

    • Configuration directory: ~/.config/dfbu/ (AppImage) or DFBU/data/ (source)
    • Default settings with sensible defaults
    • Empty dotfile library (ready for your entries)

Interface Overview

DFBU uses a tabbed interface with four main sections:

Tab Purpose
Backup Select dotfiles and execute backups
Restore Browse backups and restore files
Configuration Modify backup settings and options
Log View operation logs and statistics

Backup Tab

Adding Dotfiles

Method 1: Using Add Button

  1. Click "Add" button (or press Ctrl+N)
  2. Enter dotfile information:
    • Application: Unique name (e.g., "Bash", "Vim", "Firefox")
    • Description: Brief description of configuration
    • Path: Click "Browse" to select file or directory
    • Tags: Optional comma-separated tags (e.g., "shell, terminal")
  3. Click "OK" to save

Method 2: Manual Configuration

  1. Click "Edit Config" button
  2. Edit dotfiles.yaml in your text editor: 
    Bash:
  description: Bash shell configuration
  paths:
    - ~/.bashrc
    - ~/.bash_aliases
  tags: shell, terminal
  3. Save file
  4. Click "Validate Config" to verify syntax
  5. Reload configuration

Managing Dotfiles

Edit Dotfile:

  1. Select dotfile in table
  2. Click "Edit" button
  3. Modify fields
  4. Click "OK" to save

Remove Dotfile:

  1. Select dotfile in table
  2. Click "Remove" button
  3. Confirm deletion

Toggle Selection:

  • Include All: Checkbox in header row
  • Exclude Individual: Uncheck specific dotfiles

Filtering Dotfiles

Filter Input (top of Backup tab):

  • Type application name, tag, or path fragment
  • Table updates in real-time
  • Clear filter with "X" button

Hide Missing Checkbox:

  • Enable to hide dotfiles with non-existent source paths
  • Useful for multi-machine configurations
  • Missing files shown in gray when unchecked

Executing Backups

Basic Backup Workflow:

  1. Select Dotfiles: Check dotfiles to include in backup
  2. Choose Mode: Select mirror and/or archive in Configuration tab
  3. Click Backup: Press "Backup" button (or Ctrl+B)
  4. Monitor Progress: Watch progress bar and log output
  5. Review Results: Check statistics panel for completion summary

Progress Indicators:

  • Progress Bar: 0-100% completion
  • Status Text: Current operation (e.g., "Copying ~/.bashrc")
  • Log Pane: Detailed file-by-file output
  • Statistics: Files processed, skipped, failed, total size

Verbose Logging:

  • Toggle "Verbose" button in log pane toolbar
  • Shows full destination paths for all operations
  • Useful for verifying backup locations

Size Warnings:

  • If size check enabled, DFBU warns about large files
  • Size Warning Dialog shows:
    • Files exceeding thresholds
    • File sizes and severity levels (Warning/Alert/Critical)
    • Option to Continue or Abort
  • Adjust thresholds in Configuration tab

Backup Modes

Mirror Backup:

  • Creates readable directory structure
  • Files remain uncompressed
  • Easy browsing and selective restoration
  • Output: ~/backups/mirror/hostname/

Archive Backup:

  • Creates compressed .tar.gz archive
  • Space-efficient storage
  • Timestamped archives with rotation
  • Output: ~/backups/archives/hostname/backup-YYYYMMDD-HHMMSS.tar.gz

Dual Mode:

  • Enable both mirror and archive simultaneously
  • Best of both worlds: accessibility and space efficiency
  • Recommended for comprehensive backup strategy

Restore Tab

Browsing Backups

Mirror Backup Restore:

  1. Navigate to Restore tab
  2. Browse mirror backup directory tree
  3. Select files or directories to restore
  4. Click "Restore" button (or Ctrl+R)

Archive Backup Restore:

  1. Navigate to Restore tab
  2. Select archive from list (sorted by timestamp)
  3. Archive is extracted to temporary location
  4. Browse extracted contents
  5. Select files to restore
  6. Click "Restore"

Restore Options

Pre-Restore Backup:

  • Enabled by default (pre_restore_backup: true)
  • Creates timestamped backup of existing files before overwriting
  • Backup location: ~/.local/share/dfbu/restore-backups/
  • TOML manifest documents all backed-up files

Restore to Original Location:

  • Default behavior: restores files to original paths
  • Preserves directory structure
  • Overwrites existing files (after safety backup)

Restore Progress:

  • Progress bar shows completion percentage
  • Log pane displays each file restored
  • Statistics panel shows restore summary

Restore Safety

Safety Measures:

  1. Pre-restore backup: Existing files backed up first
  2. Confirmation dialog: Warns before overwriting
  3. Abort option: Cancel mid-restoration if needed
  4. Verification: Optional post-restore integrity check

Undoing Restores:

  • Navigate to ~/.local/share/dfbu/restore-backups/
  • Find most recent backup by timestamp
  • Manually restore files from safety backup

Configuration Tab

Backup Paths

Mirror Directory:

  • Field: "Mirror Backup Directory"
  • Browse: Select directory via file picker
  • Purpose: Destination for readable backups
  • Recommendation: Local fast storage or Git repository

Archive Directory:

  • Field: "Archive Backup Directory"
  • Browse: Select directory via file picker
  • Purpose: Destination for compressed archives
  • Recommendation: External drive or cloud storage

Restore Backup Directory:

  • Field: "Restore Backup Directory"
  • Default: ~/.local/share/dfbu/restore-backups/
  • Purpose: Pre-restore safety backups
  • Recommendation: Keep default unless space constrained

Backup Options

Mode Selection:

  • ☑ Mirror Backup: Enable readable directory backups
  • ☑ Archive Backup: Enable compressed archives
  • Both can be enabled simultaneously

Archive Settings:

  • Compression Level: Slider (1-9)
    • 1: Fast, larger files
    • 5: Balanced (default)
    • 9: Maximum compression, slower
  • Max Archives: Number of archives to retain (auto-rotation)

Organization:

  • ☑ Hostname Subdirectory: Create subdirectory per hostname
  • ☑ Date Subdirectory: Organize archives by date

Verification Options

  • ☑ Verify After Backup: Enable post-backup verification
  • ☑ Hash Verification: Enable SHA-256 hash checking

Verification Process:

  1. Existence check: Confirms files exist in backup
  2. Size verification: Compares source and backup sizes
  3. Hash verification: Compares SHA-256 hashes (if enabled)

Verification Report:

  • Displayed in dialog after backup completion
  • Shows pass/fail status for each check
  • Logs failures for investigation

Size Management

  • ☑ Enable Size Check: Enable pre-backup size analysis
  • Warning Threshold: Yellow indicator (default: 10 MB)
  • Alert Threshold: Orange indicator (default: 100 MB)
  • Critical Threshold: Red indicator (default: 1024 MB)

Size Warning Dialog:

  • Lists files exceeding thresholds
  • Shows severity levels and file sizes
  • Options: Continue or Abort backup

Configuration Actions

Edit Config:

  • Opens dotfiles.yaml in system default editor
  • Direct editing of dotfile library
  • Remember to validate after manual edits

Validate Config:

  • Checks YAML syntax in configuration files
  • Reports errors with line numbers
  • Option to reload after fixes

Export Config:

  • Exports settings.yaml and dotfiles.yaml
  • Choose destination directory
  • Useful for backup or sharing configurations

Profile Management

Creating Profiles

  1. Click "Profiles" button (Configuration tab)
  2. Click "New Profile"
  3. Enter profile information:
    • Name: Unique profile identifier
    • Description: Profile purpose
    • Exclusions: Dotfiles to exclude
    • Option Overrides: Custom settings for this profile
  4. Click "Save"

Using Profiles

Switch Profile:

  1. Click "Profiles" button
  2. Select profile from list
  3. Click "Load"
  4. Backup tab reflects profile exclusions
  5. Options use profile overrides

Edit Profile:

  1. Select profile from list
  2. Click "Edit"
  3. Modify settings
  4. Click "Save"

Delete Profile:

  1. Select profile
  2. Click "Delete"
  3. Confirm deletion

Profile Use Cases

Work Profile:

  • Exclude personal configs (games, social media)
  • Enable maximum compression for cloud upload
  • Enable verification for critical files

Personal Profile:

  • Exclude work-related configs
  • Mirror backup to Git repository
  • Faster compression for frequent backups

Minimal Profile:

  • Essential dotfiles only (shell, editor, git)
  • Quick backups for testing
  • Minimal storage footprint

Keyboard Shortcuts

Shortcut Action
Ctrl+B Start Backup
Ctrl+R Start Restore
Ctrl+V Verify Backup
Ctrl+N Add New Dotfile
F1 Open Help
Ctrl+Q Quit Application

Common Workflows

Daily Backup Workflow

  1. Launch DFBU
  2. Review dotfile selection (use filter if needed)
  3. Press Ctrl+B to start backup
  4. Monitor progress in log pane
  5. Review statistics on completion
  6. Close DFBU

Time: 30 seconds - 2 minutes depending on file count

Multi-Machine Setup

Machine 1 (Primary):

  1. Configure dotfiles for all applications
  2. Export configuration (Export Config button)
  3. Sync configuration to shared location (Git, cloud, USB)

Machine 2 (Secondary):

  1. Install DFBU
  2. Import configuration files to ~/.config/dfbu/
  3. Enable "Hide Missing" checkbox
  4. Backup only present dotfiles
  5. Use machine-specific profiles if needed

Migration to New System

Old System:

  1. Execute full backup (mirror + archive)
  2. Verify backup completion
  3. Copy backup directories to external drive or cloud

New System:

  1. Install DFBU
  2. Copy backup directories to new system
  3. Navigate to Restore tab
  4. Select files to restore
  5. Execute restore operation
  6. Verify restored files

Testing New Configurations

Before Changes:

  1. Create "Pre-Change" profile with current setup
  2. Execute backup with timestamp in name
  3. Proceed with configuration experiments

After Changes:

  1. Test new configuration
  2. If satisfactory: Update regular backup
  3. If problematic: Restore from "Pre-Change" backup

Regular Maintenance

Weekly:

  • Review and clean exclusions
  • Check backup directory disk space
  • Verify recent backups exist

Monthly:

  • Review dotfile library for obsolete entries
  • Update .dfbuignore patterns
  • Archive old backups to cold storage

Annually:

  • Review and update profiles
  • Clean old restore backups
  • Update backup path locations if needed

Best Practices

Backup Strategy

3-2-1 Rule:

  • 3 copies of data (original + 2 backups)
  • 2 different storage types (mirror + archive)
  • 1 off-site backup (cloud or external drive)

DFBU supports this with:

  • Original files on system
  • Mirror backup on local storage
  • Archive backup on cloud/external drive

What to Backup

Essential:

  • Shell configurations (.bashrc, .zshrc)
  • Editor configurations (.vimrc, .config/nvim/)
  • Git configuration (.gitconfig)
  • SSH configuration (.ssh/config)

Important:

  • Terminal emulator configs
  • Development tool configurations
  • Desktop environment settings

Optional:

  • Application caches (usually excluded)
  • Browser profiles (large, change frequently)
  • Game configurations

What NOT to Backup

Never Backup:

  • Private SSH keys (.ssh/id_rsa) - store securely, not in backups
  • GPG private keys - use dedicated key management
  • Password databases - use encrypted password managers
  • Session tokens and cookies
  • Cached data that regenerates

Use .dfbuignore to exclude:

  • Temporary files
  • Cache directories
  • Build artifacts
  • Log files

Backup Frequency

Daily: Essential dotfiles if actively developing Weekly: General configurations and settings Monthly: Complete system backup including optional configs Before Major Changes: System upgrades, distribution migrations

Navigation: Home | Features | Configuration | Troubleshooting

Clone this wiki locally