1. Overview
rsync is a useful and efficient synchronization tool for transferring files and directories.
rsync works in the archive mode if the -a option is passed. It synchronizes the directories recursively. It also keeps the ownership of users and groups, permissions, symbolic links (symlinks), and timestamps. In fact, it’s a collection of the -rlptgoD options.
In this tutorial, we’ll examine these options that constitute the -a option.
2. The Options of the Archive Mode
We’ll discuss each option of the archive mode in this section.
2.1. The -r Option
The -r option of rsync is for copying directories recursively. Let’s discuss it using the following directory, source_directory:
$ pwd
/home/alice
$ ls –l source_directory/
total 4
drwxr-wr-w 2 alice alice 4096 Aug 12 17:35 directory1
-rw-r--r-- 1 alice alice 0 Aug 12 17:35 file1
We have a subdirectory directory1 and a file file1 in source_directory.
Now, we’ll copy the contents of source_directory to another directory, destination_directory, using rsync:
$ rm –rf destination_directory
$ rsync source_directory/* destination_directory/
skipping directory directory1
We didn’t use any options of rsync. It seems that we couldn’t copy the subdirectory directory1. Let’s check the contents of destination_directory:
$ ls –l destination_directory/
total 0
-rw-r--r-- 1 alice alice 0 12 Aug 12 17:40 file1
We could copy only file1.
We must use the -r option of rsync to copy the subdirectory directory1:
$ rm –rf destination_directory
$ rsync –r source_directory/* destination_directory/
We didn’t get an error message as before. Let’s check the contents of destination_directory again:
$ ls –l destination_directory/
total 4
drwxr-wr-w 2 alice alice 4096 Aug 12 17:41 directory1
-rw-r--r-- 1 alice alice 0 Aug 12 17:41 file1
So, we were successful in copying the subdirectory directory1 this time.
2.2. The -l Option
The -l option of rsync is for copying symlinks. When we use this option, rsync copies the symlinks in a source directory as symlinks to a destination directory.
We’ll use the following directory for examining the -l option:
$ ls –l source_directory/
total 0
-rw-r--r-- 1 alice alice 0 Aug 12 17:42 file1
lrwxrwxrwx 1 alice alice 5 Aug 12 17:42 slink1 -> file1
We have a regular file, file1, and a symlink to file1, slink1. Let’s try to copy the contents of source_directory to destination_directory without using the -l option of rsync:
$ rm –rf destination_directory
$ rsync source_directory/* destination_directory/
skipping non-regular file “slink1”
Let’s check the contents of destination_directory:
$ ls –l destination_directory/
total 0
-rw-r--r-- 1 alice alice 0 Aug 12 17:43 file1
We couldn’t copy slink1 since we didn’t use the -l option.
Now, let’s copy the contents of source_directory to destination_directory once more, but using the -l option:
$ rm –rf destination_directory
$ rsync –l source_directory/* destination_directory/
We didn’t get an error message this time. Let’s check the contents of destination_directory:
$ ls –l destination_directory/
total 0
-rw-r--r-- 1 alice alice 0 Aug 12 17:44 file1
lrwxrwxrwx 1 alice alice 5 Aug 12 17:44 slink1 -> file1
Now, we were able to copy the symlink as we used the -l option.
2.3. The -p Option
Let’s consider the following source and destination directories:
$ ls –l source_directory/
total 0
-rw-r--r-- 1 alice alice 0 Aug 12 17:50 file1
$ ls –l destination_directory/
total 0
-rw------- 1 alice alice 0 Aug 12 17:39 file1
Both directories have the same file, file1, but the permissions of the files are different. The file in source_directory has the -rw-r–r– permissions, but the file in destination_directory has the -rw——- permissions.
Now, let’s first copy the contents of source_directory to destination_directory without using any options, and then check the file permissions of the copied file1 in destination_directory:
$ rsync source_directory/* destination_directory/
$ ls –l destination_directory/
total 0
-rw------- 1 alice alice 0 Aug 12 17:55 file1
We copied the file without any errors. However, the file permissions of file1 in destination_directory are the same as before updating it with rsync.
The -p option of rsync is for preserving the file permissions from the source directory. Let’s repeat the last copy operation by using the -p option of rsync:
$ rsync –p source_directory/* destination_directory/
$ ls –l destination_directory/
total 0
-rw-r--r-- 1 alice alice 0 Aug 12 17:56 file1
Now, the file permissions of the source and the destination files are the same. So, we kept the file permissions from the source directory while copying the file with rsync.
2.4. The -t Option
If we copy files using rsync without any options, rsync doesn’t preserve the modification times of the files. Let’s verify this using the following file:
$ ls –l source_directory/file1
total 0
-rw-r--r-- 1 alice alice 0 Aug 12 20:00 source_directory/file1
The modification time of file1 in source_directory is Aug 12 20:00. Now, let’s copy this file to destination_directory without using any options:
$ rm –f destination_directory/file1
$ date; rsync source_directory/file1 destination_directory/
Fri Aug 12 20:05:11 +01 2022
Let’s check the modification time of file1 in destination_directory:
$ ls –l destination_directory/file1
total 0
-rw-r--r-- 1 alice alice 0 Aug 12 20:05 destination_directory/file1
As we see, the modification time of file1 in destination_directory is different from the modification time of file1 in source_directory. In fact, it’s the creation time of the file in destination_directory. We recorded this time using the date command while copying the file.
In order to keep the modification time of the file from the source directory, we must use the -t option of rsync:
$ date; rsync –t source_directory/file1 destination_directory/
Fri Aug 12 20:10:43 +01 2022
$ ls -l destination_directory/file1
total 0
-rw-r--r-- 1 alice alice 0 Aug 12 20:00 destination_directory/file1
Now, both files in the source and destination directories have the same modification time.
2.5. The -g Option
We’ll use the following directory for examining the -g option:
$ ls –l source_directory/
total 0
-rw-r--r-- 1 alice staff 0 Aug 12 20:05 file1
$ ls –l destination_directory/file1
total 0
-rw-r--r-- 1 alice alice 0 Aug 12 19:05 file1
We have the file file1 in both directories. The files have the same owner but different groups. file1 in source_directory has the group staff. On the other hand, file1 in destination_directory has the group alice. The primary group for the user alice is alice. staff is a secondary group for the user alice.
Let’s copy the file file1 in source_directory to destination_directory using rsync:
$ rsync source_directory/file1 destination_directory/
$ ls -l destination_directory/file1
total 0
-rw-r--r-- 1 alice alice 0 Aug 12 20:10 destination_directory/file1
We didn’t use any options while using rsync. Since the group alice is the primary group for the user alice, the file file1 in destination_directory had the group alice.
What if we want to preserve the group of the file in source_directory? Then, we must use the -g option:
$ rsync –g source_directory/file1 destination_directory/
$ ls -l destination_directory/file1
total 0
-rw-r--r-- 1 alice staff 0 Aug 12 20:11 destination_directory/file1
Now, destination_directory/file1 has the same group as source_directory/file1 thanks to the -g option of rsync.
2.6. The -o Option
The -o option of rsync is for preserving the owner of the source file while copying it to the destination. We must have root privileges to preserve ownership.
We’ll use the following directory for examining the -o option:
$ ls –l source_directory/
total 0
-rw-r--r-- 1 bob staff 0 Aug 12 21:45 file1
The owner of file1 is the user bob. Let’s have the user alice try to copy it to destination_directory using rsync:
$ rsync source_directory/file1 destination_directory/
$ whoami
alice
$ ls -l destination_directory/file1
total 0
-rw-r--r-- 1 alice alice 0 Aug 12 21:46 destination_directory/file1
The owner of the copied file in destination_directory is the user alice. We couldn’t preserve the owner of the source file, which is bob.
Now, let’s have the user alice copy file1 in source_directory using the -o option of rsync:
$ rm –f destination_directory/file1
$ whoami
alice
$ rsync –o source_directory/file1 destination_directory/
$ ls -l destination_directory/file1
total 0
-rw-r--r-- 1 alice alice 0 Aug 12 21:47 destination_directory/file1
We still couldn’t keep the owner of the file as the user alice copied the file. We must copy it with root privileges. So, let’s copy the file once more with root privileges:
$ rm –f destination_directory/file1
$ whoami
root
$ rsync –o source_directory/file1 destination_directory/
$ ls -l destination_directory/file1
total 0
-rw-r--r-- 1 bob root 0 Aug 12 21:48 destination_directory/file1
This time, we were able to keep the owner of the file. However, the group of file1 became root. If we want to keep the group of the original file in source_directory, we can use the -g option as we saw before:
$ rm –f destination_directory/file1
$ whoami
root
$ rsync –go source_directory/file1 destination_directory/
$ ls -l destination_directory/file1
total 0
-rw-r--r-- 1 bob staff 0 Aug 12 21:49 destination_directory/file1
Now, both the owner and group of the source file were preserved.
2.7. The -D Option
The -D option of rsync is the combination of the –devices and —specials options.
The –devices option is for copying device files. We must have root privileges for copying device files.
The –specials option is necessary for copying files such as FIFO files and named sockets.
First, we’ll try to copy a device file using rsync. Let’s copy /dev/null, which is a device file, to destination_directory:
$ rm –rf destination_directory
$ rsync /dev/null destination_directory/
skipping non-regular file “null”
We didn’t use any of the options of rsync, and we couldn’t copy the device file /dev/null. Let’s try to copy it using the -D option:
$ rm –rf destination_directory
$ rsync –D /dev/null destination_directory/
$ ls –l destination_directory/
total 0
crw-r--r-- 1 root root 1, 3 Aug 12 18:02 null
We were successful in copying the device file this time.
Now, we’ll try to copy a FIFO file using rsync. First, let’s clean the contents of source_directory, and then create a FIFO file in source_directory using the mkfifo command:
$ rm –rf source_directory/*
$ mkfifo source_directory/fifo_file
$ ls –l source_directory/
total 0
prw-r--r-- 1 alice alice 0 Aug 12 19:00 fifo_file
Having created the FIFO file in the source directory, let’s try to copy it to the destination directory without using any options of rsync:
$ rm –rf destination_directory
$ rsync source_directory/* destination_directory/
skipping non-regular file “fifo_file”
rysnc omitted to copy the FIFO file. Now, let’s copy it using the -D option:
$ rsync –D source_directory/* destination_directory/
$ ls –l destination_directory/
total 0
prw-r--r-- 1 alice alice 0 Aug 12 19:02 fifo_file
We were successful in copying the FIFO file when we used the -D option.
3. Conclusion
In this article, we discussed each option of the archive mode of rsync.
First, we learned that the -a option of rsync is equivalent to -rlptgoD options.
The -r option is for recursively transferring directories.
The -l option is for keeping symlinks.
The -p and the -t options are for keeping file permissions and modification times of source files, respectively.
The -g and the -o options are necessary for keeping the group and the owner of source files, respectively. The -o option needs root privileges.
Finally, the -D option is for copying device files and special files such as FIFO files and named sockets. We must have root privileges for transferring device files.