To update files transferred in previous rsync executions, use the
-u (update) flag. This option ensures that rsync only transfers files that are newer on the source than those on the destination, preventing the overwriting of newer local copies while keeping your remote data synchronized with the most recent changes from the source system efficiently and safely.
Understanding the Update Mechanism
When you run
rsync without specific flags, it typically compares file modification times and sizes to determine what needs to be moved. If a file exists on both the source and destination, rsync checks if the source version is newer. However, in many workflows, you might have modified a file locally after the initial transfer, or the destination file might have been touched by another process, changing its timestamp without altering its content. In these scenarios, a standard sync might skip the update or overwrite your local work depending on the configuration.
The
-u flag, which stands for
update, modifies this behavior specifically. It tells rsync to skip files that exist on the destination and have a newer modification time than the corresponding source file. This is crucial for incremental backups or when you want to ensure that the destination reflects the latest state of the source without destroying any work done on the destination side since the last sync. It essentially acts as a safety net against accidental data loss during synchronization tasks.
Basic Syntax for Updating Files
Implementing this feature requires adding the
-u flag to your standard rsync command line. The basic structure remains similar to a regular copy operation, but the logic behind the transfer changes. You specify the source directory or file, followed by the destination path. For example, to synchronize a local directory to a remote server while updating only changed files, you would use:
rsync -avuz /path/to/source/ user@remote:/path/to/destination/
In this command,
-a preserves attributes like permissions and timestamps,
-v provides verbose output so you can see what is happening,
-u enables the update mode, and
-z compresses data during transfer to improve speed. The trailing slash on the source path is important; it tells rsync to copy the contents of the directory rather than the directory itself. Without it, the entire folder structure might be recreated under the destination name.
If you are working with local directories only, the syntax is nearly identical. Simply replace the remote user and host with the target local path. This allows you to maintain two local copies where one is always an updated mirror of the other, provided no newer files were created on the target side independently.
Combining Update with Other Flags
While
-u is powerful on its own, it is rarely used in isolation. It works best when combined with the archive mode (
-a). The archive mode is a shorthand for several other flags, including
-rlptgoD, which recursively copies directories, preserves links, permissions, ownership, and group settings. By using
-au, you get the full benefits of an archive sync but with the added safety of the update filter.
You should also consider using the
--delete flag with caution. When
--delete is active, rsync will remove files from the destination that no longer exist in the source. If you combine
--delete with
-u, you might encounter unexpected results. Specifically, if a file was deleted on the source but still exists on the destination because it was newer,
-u will prevent its deletion. This can lead to a state where the destination contains "orphaned" files that are not present on the source. Therefore, carefully evaluate whether you need strict mirroring or just an update mechanism.
For more complex scenarios involving exclusions, such as skipping certain subfolders, you can integrate exclusion patterns into your command. This complements the update logic by ensuring that irrelevant data is not even considered for comparison. See
Excluding Subfolders when Copying Files between Directories using rsync in Arch Linux for details on managing these filters effectively.
Common Pitfalls and Verification
One common mistake is assuming that
-u protects against all forms of data corruption. It only protects based on modification time. If a file is modified on the destination but its timestamp is manually set to an older value using
touch, rsync will overwrite it. Always verify your command with the
--dry-run or
-n flag before executing critical transfers. This simulates the operation and prints out exactly which files would be transferred, allowing you to confirm that the update logic is behaving as expected.
Another consideration is network latency. When syncing large datasets over slow connections, the update check happens for every single file. This can be time-consuming. Using the
--checksum option (
-c) forces rsync to compare checksums instead of just modification times. While this is slower, it is more accurate for detecting actual content changes, especially if timestamps have been altered or are unreliable due to filesystem quirks. However, for most daily updates, the time-based check provided by
-u is sufficient and much faster.
It is also worth noting how
rsync handles partial transfers. If a transfer is interrupted, the destination file may be incomplete. A subsequent run with
-u will see the incomplete file as having an older timestamp (if the interruption happened quickly) or a newer timestamp (if the file was partially written). To handle this robustly, consider using
--partial to keep partially transferred files, ensuring that resumed transfers do not start from scratch.
For further insights on managing file attributes during these operations, refer to
How to Fix Rsync Not Setting File Permissions Correctly when Transferring Local to Remote. Ensuring permissions are correct helps maintain the integrity of the files once they are updated.
Frequently Asked Questions
Does rsync -u delete files missing from the source?
No, the
-u flag only prevents overwriting newer files on the destination. It does not remove files that exist on the destination but not on the source. To achieve deletion of orphaned files, you must explicitly add the
--delete flag to your command.
What happens if I modify a file on the destination after syncing?
If you modify a file on the destination, its modification time becomes newer than the source. On the next sync with
-u, rsync will skip this file, preserving your local changes. This is useful for maintaining patches or configurations made directly on the server.
Can I use -u with ssh encryption?
Yes,
-u works seamlessly with SSH encrypted transfers. You simply include the standard SSH connection details in your rsync command, such as specifying the user and host. The update logic operates on the file metadata regardless of the transport layer security.
Is there a risk of data loss when using -u?
There is minimal risk if used correctly. The primary risk is unintentionally preserving outdated files if their timestamps are manipulated. Always test with
--dry-run first to ensure that the files you expect to be updated are indeed being processed by the tool.
How does -u differ from --ignore-existing?
--ignore-existing skips files that already exist on the destination, regardless of their age.
-u only skips files that are newer on the destination. This means
-u will still update existing files if the source is newer, whereas
--ignore-existing never updates them once they are present.