btrfs-replace - Linux


The btrfs-replace command allows you to replace the data and/or metadata of an existing file or directory with another file or directory in a Btrfs filesystem. This is useful for atomically modifying or replacing data, preserving file timestamps and permissions.


btrfs-replace [OPTIONS] <TARGET> <SOURCE>


  • -f, –force: Bypass safety checks and forcibly perform the replacement.
  • -t, –atime: Retain original access time of the TARGET.
  • -c, –ctime: Retain original change time of the TARGET.
  • -m, –mtime: Retain original modification time of the TARGET.
  • -d, –device: Specify the device name of the Btrfs filesystem.


Replace File Data

# Replace the contents of file1 with those of file2
btrfs-replace file1 file2

Replace File and Metadata

# Replace file1 with file2, including metadata
btrfs-replace -m -c -t file1 file2

Replace Directory with Another

# Replace directory1 with directory2
btrfs-replace directory1 directory2

Common Issues

  • Permission denied: Ensure you have sufficient permissions to modify both TARGET and SOURCE.
  • File or directory not found: Make sure the specified files/directories exist.
  • Invalid Btrfs filesystem: Verify that the provided device is a valid Btrfs filesystem.


btrfs-replace can be used with other Btrfs tools:

  • btrfs send/receive: Use btrfs-replace to atomically update files during a snapshot restore process.

Related Commands

  • cp: Copy files or directories.
  • mv: Move files or directories.
  • ln: Create symbolic links.