How omarchy-refresh-config Copies Defaults to ~/.config/ with Automatic Backup

omarchy-refresh-config synchronizes Omarchy's default configuration files into ~/.config/ while automatically creating timestamped backups of existing user files to prevent data loss.

The omarchy-refresh-config command is a core utility in the Omarchy Quattro repository that manages configuration deployment safely. When updating dotfiles or migrating to new defaults, this script ensures that any existing user customizations are preserved through automatic backups before overwriting them with repository defaults.

Core Implementation in bin/omarchy-refresh-config

The primary logic resides in bin/omarchy-refresh-config, a shell script designed to be invoked by wrapper commands throughout the Omarchy ecosystem. According to the source code in the Omarchy Quattro repository, the command follows a strict three-phase process:

Source and Destination Resolution

First, the script resolves the source path to $OMARCHY_PATH/config/<relative-path> and the destination to $HOME/.config/<relative-path>. This convention ensures that all default configurations live within the repository's config/ directory while user-specific files are deployed to the standard XDG configuration location.

Path Traversal Protection

Before performing any file operations, the script validates that the provided <relative-path> does not contain .. components. This hardening measure, documented in plans/dots.md, prevents directory-escape attacks by aborting with a clear error message if an illegal path is detected.

Automatic Backup Creation

If a file already exists at the destination, the script renames it to <relative-path>.bak.<timestamp> using the current Unix epoch. As noted in plans/dots.md, this approach intentionally "litters" *.bak.<timestamp> files next to originals, creating unique, recoverable snapshots without prompting the user.

Atomic Copy Operation

Finally, the script creates the target directory hierarchy with mkdir -p if necessary, then executes cp -a to copy the source file while preserving permissions, ownership, and symlinks. The command exits with status 0 on success or writes an error message to stderr and returns a non-zero status on failure.

Practical Usage Examples

Here is how omarchy-refresh-config behaves in typical Omarchy workflows:

# Refresh a single configuration file with automatic backup

omarchy-refresh-config hypr/bindings.lua

# Copies $OMARCHY_PATH/config/hypr/bindings.lua → $HOME/.config/hypr/bindings.lua

# Existing file backed up to: $HOME/.config/hypr/bindings.lua.bak.1696398425

# Batch refresh via wrapper scripts

omarchy-refresh-hyprland

# Internally calls omarchy-refresh-config for multiple files:

# hypr/.luarc.json, hypr/autostart.lua, hypr/monitors.lua, etc.

# Migration script usage (from migrations/1788745941.sh)

omarchy-refresh-config kitty/kitty.conf

# Safely adds new default configs while backing up existing user settings

Security and Validation Features

The implementation prioritizes safety through several mechanisms verified in test/shell.d/refresh-config-test.sh:

• Path sanitization: Rejects any relative path containing parent directory references (..)
• Atomic backups: Uses timestamped files rather than overwriting previous backups
• POSIX compliance: Relies only on standard utilities (cp, mkdir, date) for portability

Integration with Omarchy Refresh Wrappers

The command serves as a building block for higher-level refresh scripts. Throughout the bin/ directory, wrappers like omarchy-refresh-hyprland and omarchy-refresh-tmux invoke omarchy-refresh-config repeatedly to synchronize entire configuration suites. This architecture keeps the core utility thin and focused while allowing complex refresh logic in specialized wrappers.

Summary

• omarchy-refresh-config deploys files from $OMARCHY_PATH/config/ to $HOME/.config/ with automatic backup
• Existing files are preserved as <filename>.bak.<unix-timestamp> before being overwritten
• Path traversal attacks are mitigated by rejecting paths containing .. components
• The script uses cp -a to preserve file permissions and metadata
• Exit status 0 indicates success; non-zero indicates error with stderr output
• Used extensively by wrapper scripts like omarchy-refresh-hyprland for batch operations

Frequently Asked Questions

What happens if I run omarchy-refresh-config on a file that doesn't exist in the repository?

The command checks for the existence of the source file at $OMARCHY_PATH/config/<relative-path> before proceeding. If the source is missing, it writes an error message to stderr and exits with a non-zero status code, leaving your existing configuration untouched.

How do I restore a configuration from a backup created by omarchy-refresh-config?

Locate the timestamped backup file (e.g., config.bak.1696398425) in the same directory as your current configuration, then rename it back to the original filename or copy its contents into your active config. The backups use Unix epoch timestamps for uniqueness and chronological sorting.

Does omarchy-refresh-config handle directories or only individual files?

While primarily used for individual configuration files, the script creates necessary directory hierarchies using mkdir -p before copying. However, each invocation typically processes one relative path, so wrapper scripts iterate over multiple files to handle complex directory trees.

Can omarchy-refresh-config be used outside of the Omarchy ecosystem?

Yes, provided the $OMARCHY_PATH environment variable is set to point to your configuration repository. The script is self-contained and uses only POSIX utilities, making it portable to any system with standard shell tools installed, though it is designed specifically for the Omarchy Quattro workflow.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}