# Version Management and Backup Recovery

    library(boilerplate)

## Overview

The boilerplate package provides comprehensive version management features to help you track changes, manage different versions of your databases, and recover from backups when needed.

## Managing Multiple Versions

When working on a project over time, you’ll accumulate different versions of your databases. The boilerplate package helps manage these:

    # See all available database files
    # Using a temporary directory for this example
    temp_version <- file.path(tempdir(), "version_example")
    boilerplate_init(data_path = temp_version, create_empty = FALSE, create_dirs = TRUE, confirm = FALSE, quiet = TRUE)

    files <- boilerplate_list_files(data_path = temp_version)
    print(files)

    # Check what versions exist for methods
    methods_files <- boilerplate_list_files(data_path = temp_version, category = "methods")

The `boilerplate_list_files()` function organises files into: - Standard files: Current working versions - Timestamped versions: Saved with timestamps - Backup files: Automatic backups created before overwrites

## Working with Timestamped Versions

Save important milestones with timestamps:

    # Load your database
    db <- boilerplate_import(data_path = temp_version, quiet = TRUE)

    # Save with timestamp before major revision
    boilerplate_save(
      db,
      data_path = temp_version,
      timestamp = TRUE,
      confirm = FALSE,
      quiet = FALSE
    )
    #> ✔ Saved unified database to: boilerplate_unified_20240115_143022.rds

    # Later, import specific version
    # Note: Replace with your actual timestamped filename
    db_milestone <- boilerplate_import(
      data_path = "path/to/your/boilerplate_unified_20240115_143022.rds"
    )

## Backup and Recovery

If something goes wrong, recover from automatic backups:

    # List available backups
    files <- boilerplate_list_files(data_path = temp_version)
    # Look at files$backups for backup files

    # View latest backup without restoring
    backup_db <- boilerplate_restore_backup(data_path = temp_version, category = "methods")

    # Restore latest backup as current version
    boilerplate_restore_backup(
      data_path = temp_version,
      category = "methods",
      restore = TRUE,
      confirm = TRUE
    )
    #> ✔ Restored backup from 20240110_120000

    # Restore specific backup by timestamp
    boilerplate_restore_backup(
      data_path = temp_version,
      category = "methods",
      backup_version = "20240110_120000",
      restore = TRUE,
      confirm = FALSE
    )

## Version Management Workflow

Here’s a typical workflow for managing versions:

    # 1. Check current versions
    files <- boilerplate_list_files(data_path = temp_version, category = "methods")

    # 2. Save current work with timestamp
    methods_db <- boilerplate_import("methods", data_path = temp_version, quiet = TRUE)
    boilerplate_save(
      methods_db,
      data_path = temp_version,
      category = "methods",
      timestamp = TRUE,
      confirm = FALSE,
      quiet = TRUE
    )

    # 3. Make changes
    methods_db$new_method <- "New methodology text"
    boilerplate_save(methods_db, data_path = temp_version, category = "methods", confirm = FALSE, quiet = TRUE)

    # 4. If changes were problematic, restore from backup
    boilerplate_restore_backup(data_path = temp_version, category = "methods", restore = TRUE, confirm = FALSE)

    # 5. Compare versions
    current <- boilerplate_import("methods", data_path = temp_version, quiet = TRUE)
    old_version <- boilerplate_import(
      data_path = "path/to/your/methods_db_20240110_120000.rds"
    )

## Best Practices

1. Regular timestamped saves: Save with timestamps at key milestones
2. Document changes: Use meaningful commit messages when saving
3. Clean up old versions: Periodically review and archive old versions
4. Test before overwriting: Import and check old versions before replacing

## Integration with Version Control

While the package provides its own versioning, it works well with Git:

    # Save timestamped version for Git commit
    boilerplate_save(db, data_path = temp_version, timestamp = TRUE, confirm = FALSE, quiet = TRUE)

    # Add to Git
    # git add boilerplate/data/boilerplate_unified_*.rds
    # git commit -m "Snapshot before major refactoring"

## Troubleshooting

### Finding Lost Work

If you’ve lost work, check these locations:

    # List all files including backups
    all_files <- boilerplate_list_files(data_path = temp_version)

    # Check modification times
    # The most recently modified files appear first
    print(all_files$timestamped[1:5, c("file", "modified")])
    print(all_files$backups[1:5, c("file", "modified")])

### Recovering from Corruption

If a database file becomes corrupted:

    # Try loading backup
    backup_db <- tryCatch(
      boilerplate_restore_backup(data_path = temp_version, category = "methods"),
      error = function(e) {
        message("Backup corrupted, trying older version...")
        # List files and manually load an older one
        files <- boilerplate_list_files(data_path = temp_version, category = "methods")
        if (nrow(files$timestamped) > 0) {
          boilerplate_import(data_path = files$timestamped$path[2])
        }
      }
    )

## Summary

Version management in boilerplate provides: - Automatic backups before overwrites - Timestamped saves for milestones - Easy listing and organisation of versions - Simple restoration from backups - Direct import of any version by path

This ensures you never lose work and can always recover from mistakes or explore different versions of your content.