Skip to content

Features

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

DFBU Features

DFBU provides comprehensive dotfiles and configuration backup capabilities with emphasis on safety, flexibility, and user experience.

Backup Features

Backup Modes

Mirror Backup

Creates readable directory structures that mirror source file organization:

Characteristics:

  • Preserves original directory structure
  • Files remain in plain, readable format
  • Easy browsing and manual file retrieval
  • Ideal for version control integration
  • No decompression needed for restoration

Output Structure:

~/backups/mirror/hostname/
├── bash/
│   ├── .bashrc
│   └── .bash_aliases
├── vim/
│   └── .vimrc
└── config/
    ├── alacritty/
    │   └── alacritty.yml
    └── nvim/
        └── init.vim

Use Cases:

  • Quick file inspection without extraction
  • Git repository integration for dotfiles
  • Selective file restoration
  • Human-readable backup verification

Archive Backup

Generates compressed .tar.gz archives for space-efficient storage:

Characteristics:

  • Significant space savings (typically 60-80% compression)
  • Single-file backup packages
  • Configurable compression level (1-9)
  • Timestamped archive naming
  • Automatic rotation with configurable retention

Output Structure:

~/backups/archives/hostname/
├── backup-20260207-083015.tar.gz
├── backup-20260206-210342.tar.gz
└── backup-20260205-143021.tar.gz

Configuration Options:

  • Compression Level: 1 (fastest) to 9 (maximum compression)
  • Max Archives: Automatic rotation when limit exceeded
  • Custom Naming: Optional custom archive prefixes

Use Cases:

  • Long-term backup storage
  • Network transfer (smaller file sizes)
  • Disaster recovery archives
  • Periodic snapshots with rotation

Dual Mode Operation

Execute both mirror and archive backups simultaneously:

Benefits:

  • Mirror: Quick access and selective restore
  • Archive: Compact long-term storage
  • Redundancy: Two backup formats for safety
  • Flexibility: Choose restoration method per situation

Backup Operations

Intelligent Skip Detection

DFBU avoids redundant file copies when unchanged:

Detection Methods:

  • Size Comparison: Quick initial check
  • Modification Time: Timestamp verification
  • Metadata Matching: Comprehensive comparison

Benefits:

  • Faster backup completion
  • Reduced disk I/O
  • Lower disk wear
  • Detailed skip logging

Logging:

  • Individual file skip tracking (v1.2.0+)
  • Verbose mode shows full paths
  • Skip summary in operation statistics

Progress Tracking

Real-time progress display during operations:

Progress Information:

  • Percentage completion (0-100%)
  • Current file being processed
  • Files processed vs. total count
  • Individual file status (copied/skipped/failed)

UI Elements:

  • Progress bar with percentage
  • Status text with current operation
  • Log pane with detailed file-by-file output
  • Statistics panel (files processed, skipped, total size)

Size Analysis

Pre-backup size analysis with configurable warnings (v1.0.0+):

Warning Thresholds:

  • Warning Level: 10 MB (default) - Yellow indicator
  • Alert Level: 100 MB (default) - Orange indicator
  • Critical Level: 1 GB (default) - Red indicator

Size Warning Dialog:

  • Lists large files exceeding thresholds
  • Shows file size and severity level
  • Provides Continue/Abort options
  • Configurable threshold values in settings

.dfbuignore Support:

  • Gitignore-style exclusion patterns
  • Exclude cache directories, build artifacts, logs
  • Default patterns for common exclusions
  • Custom pattern additions

Example .dfbuignore:

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

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

# Logs
*.log
logs/

Safety Features

Pre-Restore Backups

Automatic safety backups before restoration (v0.6.0+):

Behavior:

  • Creates timestamped backup of existing files
  • Only backs up files that will be overwritten
  • Stores in dedicated restore-backup directory
  • Generates TOML manifest documenting backup

Backup Location:

  • Default: ~/.local/share/dfbu/restore-backups/
  • Configurable via settings.yaml

Manifest Format (TOML):

[metadata]
timestamp = "2026-02-07T08:30:15"
source = "restore operation"
files_backed_up = 5

[[files]]
original_path = "/home/user/.bashrc"
backup_path = "restore-backup-20260207-083015/.bashrc"
size = 4096

Retention Policy:

  • Configurable maximum backups
  • Automatic cleanup of old backups
  • Sorted by timestamp (newest retained)

Verification System

Post-backup verification for data integrity (v0.8.0+):

Verification Methods:

  1. Existence Check: Confirms files copied to destination
  2. Size Verification: Compares source and backup file sizes
  3. Hash Verification: Optional SHA-256 hash comparison

Configuration Options:

  • Verify After Backup: Enable/disable automatic verification
  • Hash Verification: Enable SHA-256 hash checking
  • Verification Threshold: File size threshold for hash verification

Verification Report:

Verification Results
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ All files exist in backup
✓ All file sizes match
✓ Hash verification: 42/42 files verified
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Status: PASSED

Failure Handling:

  • Detailed error reporting for failed verifications
  • Option to retry or abort operation
  • Logged failures for investigation

Error Handling

Comprehensive error handling with recovery options (v0.9.0+):

Error Categories:

  • PERMISSION: Access denied errors
  • NOT_FOUND: Missing source files/directories
  • DISK_FULL: Insufficient storage space
  • NETWORK: Connection issues (future remote backups)
  • UNKNOWN: Unexpected errors

Recovery Dialog:

  • User-friendly error explanations
  • Recovery suggestions and remediation steps
  • Actions: Retry, Skip, Abort
  • Automatic retry for transient failures

Retry Logic:

  • Configurable retry attempts
  • Exponential backoff for network errors
  • Skip option for non-critical failures

Organization Features

Profile Management

Save and switch between backup configurations (v1.1.0+):

Profile Components:

  • Dotfile exclusion lists
  • Option overrides (compression, verification, etc.)
  • Named profiles for different scenarios
  • Active profile persistence

Use Cases:

  • Work Profile: Work-related configs only
  • Personal Profile: Personal dotfiles and settings
  • Minimal Profile: Essential files only
  • Full Profile: Complete system backup

Profile Dialog:

  • Create new profiles
  • Edit existing profiles
  • Delete unused profiles
  • Set active profile

Storage:

  • Profiles saved in profiles.yaml
  • Per-profile option overrides
  • Global settings as defaults

Tag-Based Organization

Organize dotfiles with flexible tagging:

Tag System:

  • Comma-separated tags in dotfile definitions
  • Filter by single or multiple tags
  • Category-based organization
  • Custom tag creation

Common Tags:

  • shell: Shell configurations
  • editor: Text editor configs
  • terminal: Terminal emulator settings
  • dev: Development tool configs
  • gui: GUI application configs

Tag Filtering:

  • Filter input in Backup tab
  • Search by application name, tags, or path
  • Real-time filter updates
  • Clear filter button

Exclusion Management

Temporarily exclude dotfiles from operations:

Exclusion Model:

  • All dotfiles included by default
  • Explicit exclusion via checkbox
  • Session-based persistence
  • Independent of dotfile library

Exclusion Persistence:

  • Saved in session.yaml
  • Survives application restarts
  • Per-session state management
  • Reset exclusions option

Use Cases:

  • Exclude large directories temporarily
  • Skip problematic files during testing
  • Selective backups for specific purposes
  • Temporary workflow adjustments

User Experience Features

Verbose Logging

Detailed operation logs with configurable verbosity (v1.2.0+):

Verbose Mode Toggle:

  • Toolbar button in log pane
  • Persistent setting across sessions
  • Real-time log updates

Normal Mode Output:

Copying: ~/.bashrc
Copying: ~/.vimrc
Skipped: ~/.zshrc (unchanged)

Verbose Mode Output:

Copying: ~/.bashrc
  → /home/user/backups/mirror/hostname/bash/.bashrc
Copying: ~/.vimrc
  → /home/user/backups/mirror/hostname/vim/.vimrc
Skipped: ~/.zshrc (unchanged)
  → /home/user/backups/mirror/hostname/zsh/.zshrc

Benefits:

  • Verify exact backup locations
  • Troubleshoot path issues
  • Audit backup operations
  • Detailed operation review

Individual Skip Logging

Per-file skip logging instead of batch summaries (v1.2.0+):

Previous Behavior (v1.1.x):

Skipped 10 unchanged files
Skipped 20 unchanged files

Current Behavior (v1.2.0+):

Skipped: ~/.bashrc (unchanged)
Skipped: ~/.vimrc (unchanged)
Skipped: ~/.config/alacritty/alacritty.yml (unchanged)

Benefits:

  • Identify which files were skipped
  • Verify skip decisions
  • Troubleshoot unexpected skips
  • Complete operation audit trail

Hide Missing Files

Filter dotfiles with non-existent source paths (v1.2.0+):

Hide Missing Checkbox:

  • Located on Backup tab
  • Filters out missing source files
  • Reduces visual clutter
  • Maintains full dotfile library

Use Cases:

  • Multi-machine dotfile libraries
  • Distribution-specific configs
  • Optional software configurations
  • Clean backup selection view

Configuration Tools

Enhanced configuration management tools (v1.2.0+):

Edit Config Button

Opens dotfiles.yaml in system editor:

  • Uses xdg-open for default application
  • Direct editing without file navigation
  • Immediate configuration updates
  • Reload option after edits

Validate Config Button

Validates configuration files for errors:

  • Checks YAML syntax in settings.yaml and dotfiles.yaml
  • Verifies required fields
  • Reports specific error locations
  • Option to reload after fixes

Validation Output:

Configuration Validation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ settings.yaml: Valid
✓ dotfiles.yaml: Valid
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Status: PASSED

Export Config Button

Export configuration files for backup:

  • Prompts for destination directory
  • Exports settings.yaml and dotfiles.yaml
  • Preserves comments and formatting
  • Safekeeping before major changes

Keyboard Shortcuts

Efficient operation via keyboard:

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

Customization:

  • Standard Qt shortcuts
  • Mnemonics in menus
  • Toolbar tooltips with shortcuts

File Picker Integration

Unified file/directory selection (v1.2.0+):

Unified Picker:

  • Single dialog for files and directories
  • No separate file/folder mode prompt
  • Qt QFileDialog with custom options
  • Native look and feel

Previous Behavior (v1.1.x):

[Dialog] Select type:
[ ] File
[ ] Directory

Current Behavior (v1.2.0+):

[File Picker]
File name: ___________________
Files of type: All Files (*)
[Open] [Cancel]
# Accepts both files and directories

Restore Features

Restore Tab

Browse and restore backed-up files:

Restore Interface:

  • Tree view of backed-up dotfiles
  • Source and destination path display
  • Select individual files or categories
  • Restore to original locations

Restore Operations:

  1. Scan mirror or archive backup
  2. Present files available for restoration
  3. User selects files to restore
  4. Create pre-restore safety backup
  5. Execute restoration
  6. Verify restoration success

Safety Measures:

  • Pre-restore backup creation
  • Confirmation before overwrite
  • Option to abort mid-restoration
  • Restore verification

Archive Extraction

Restore from compressed archives:

Archive Restoration:

  • Automatic archive extraction
  • Temporary extraction location
  • File selection from extracted contents
  • Cleanup after restoration

Archive Selection:

  • List available archives by timestamp
  • Preview archive contents
  • Select specific archive version
  • Restore entire archive or selective files

History & Statistics

Backup History

Track backup operations over time (v1.0.0+):

History Storage:

  • Backup operation timestamps
  • Files backed up per operation
  • Operation duration
  • Success/failure status
  • Size information

History Display:

  • Chronological operation list
  • Filter by date range
  • Search by file or operation
  • Export history report

History File: backup_history.yaml

- timestamp: "2026-02-07T08:30:15"
  operation: "mirror_backup"
  files_processed: 42
  files_skipped: 8
  total_size: 52428800
  duration: 2.5
  status: "success"

Operation Statistics

Real-time and post-operation statistics:

Statistics Display:

  • Files processed count
  • Files skipped count
  • Files failed count
  • Total size backed up
  • Operation duration
  • Average file size

Statistics Panel:

Backup Statistics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Processed: 42 files
Skipped: 8 files (unchanged)
Failed: 0 files
Total Size: 50.0 MB
Duration: 2.5 seconds
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Navigation: Home | Installation | User Guide | Configuration

Clone this wiki locally