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.