rsync の使い方 - 末尾スラッシュの違いと --delete、dry-run で事故を防ぐ同期の基本

rsync の使い方 - 末尾スラッシュの違いと --delete、dry-run で事故を防ぐ同期の基本

作成日:
読了:約53分
更新日:

当サイトは Amazon.co.jp を宣伝しリンクすることで紹介料を得る手段を提供する、Amazonアソシエイト・プログラムの参加者です。価格・在庫はリンク先の最新情報をご確認ください。

サーバーへのファイル転送、ビルド成果物のデプロイ、外付けディスクへのバックアップ。ディレクトリを丸ごと別の場所へ写す作業では、rsyncが長く使われています。2回目以降は変更のあったファイルだけを送るので速く、途中で止まってもやり直しが効きます。

一方で、rsyncは事故の話も多いコマンドです。ソースの末尾にスラッシュを付けるかどうかで出来上がるディレクトリ構造が変わり、--deleteを付けた状態で転送元を間違えると、転送先のファイルが消えます。

この記事では、rsyncの基本の書式から、末尾スラッシュの違い、--delete、-n(--dry-run)での事前確認、除外ルール、変更判定の仕組み、世代バックアップまでを、実際の実行結果を見ながら順に説明します。

先に結論: よく使う書き方の早見表

やりたいこと書き方
ディレクトリの中身を同期するrsync -av src/ dest/
ディレクトリごとコピーする(dest/src/ ができる)rsync -av src dest/
実行前に何が起きるかを見るrsync -avn src/ dest/
変更の内容を1行ずつ見るrsync -ain src/ dest/
転送元に無いファイルを転送先から消すrsync -av --delete src/ dest/
リモートへ送る(SSH経由)rsync -avz src/ user@example.com:/var/www/site/
リモートから取ってくるrsync -avz user@example.com:/var/www/site/ ./site/
ポートや鍵を指定するrsync -av -e 'ssh -p 2222 -i ~/.ssh/id_ed25519' src/ user@example.com:dest/
特定のファイルを除外するrsync -av --exclude='node_modules/' --exclude='*.log' src/ dest/
除外ルールをファイルから読むrsync -av --exclude-from=exclude.txt src/ dest/
大きなファイルを中断に強くするrsync -avP src/big.iso user@example.com:dest/
帯域を制限するrsync -av --bwlimit=5m src/ user@example.com:dest/
中身(チェックサム)で比較するrsync -avc src/ dest/
世代バックアップを取るrsync -a --link-dest=../前回 src/ backup/今回/

事故を防ぐための習慣は次の3つです。

  • ディレクトリの中身を同期するときは、ソースの末尾に/を付ける
  • --deleteを付けるコマンドは、先に-nを足して実行し、deletingの行を読む
  • 転送元と転送先の順番(左が元、右が先)を、実行前にもう一度見る

実行結果を採取した環境

この記事の実行結果は、次の環境で一時ディレクトリを作って採取しました。すべてローカル同士の転送です。

$ sw_vers
ProductName:		macOS
ProductVersion:		27.2
BuildVersion:		26B123
 
$ rsync --version
openrsync: protocol version 29
rsync version 2.6.9 compatible

macOS標準の/usr/bin/rsyncで、実体はopenrsyncです(経緯は後半の「macOS標準のrsyncの事情」で説明します)。LinuxやHomebrewで入るrsync 3系とは、統計行の書式や-iの桁数など、出力の細部が違う場合があります。オプションの意味や既定値の説明は、rsync公式のmanページ(2026年11月4日付、rsync 3.5.2のもの)を参照しています。

リモート転送のコマンドはこの記事のために実行していないため、「書式の例」として載せています。また、ls -lの出力に含まれるユーザー名はuserに置き換えています。

rsync とは

rsyncは、ファイルやディレクトリを、ローカル同士、またはリモートとの間でコピーするコマンドです。公式のmanページは、rsyncを「高速で多用途な、ローカル/リモートのファイルコピーツール」と紹介しています。作者はAndrew TridgellとPaul Mackerrasで、ライセンスはGNU General Public Licenseです。

cp や scp との違い

cp -rやscp -rは、指定したファイルを毎回すべてコピーします。rsyncは次の2段階で転送量を減らします。

  1. 転送するファイルを絞る: 転送先に同じサイズ・同じ更新時刻のファイルがあれば、そのファイルは転送しない
  2. ファイルの中の差分だけを送る: 転送が必要なファイルでも、転送先にある古い版と共通する部分は送らず、違う部分だけを送る(デルタ転送)

1万ファイルあるディレクトリのうち3ファイルだけを書き換えた場合、scp -rは1万ファイルを送り直しますが、rsyncは3ファイルだけを対象にします。

そのほかの違いは次のとおりです。

cp -rscp -rrsync
リモートとの転送不可可可
変更の無いファイルのスキップしないしないする
転送元に無いファイルの削除しないしない--deleteで可
実行前の確認(dry-run)無い無い-n
除外ルール無い無い--excludeなど
中断したファイルの再開不可不可--partialで可

SFTPやFTPでのミラーリングはlftpの記事で扱っています。転送先のサーバーにrsyncが入っていない場合は、そちらが選択肢になります。

両側に rsync が必要

SSH経由でリモートと転送する場合、rsyncは手元からSSHで接続し、リモート側でもrsyncを起動して、2つのrsyncが会話しながら転送を進めます。そのため、リモート側にもrsyncがインストールされている必要があります。入っていないと、次のようなエラーになります(表示例)。

bash: line 1: rsync: command not found
rsync: connection unexpectedly closed (0 bytes received so far) [sender]

基本の書式

rsync [オプション] 転送元 転送先

左が転送元、右が転送先です。転送元は複数並べられます。

ローカル同士

rsync -av ~/project/ /Volumes/Backup/project/

リモートへ送る・リモートから取る

リモートはユーザー@ホスト:パスの形で書きます。コロンが1つならSSHなどのリモートシェル経由です。

# ローカルからリモートへ
rsync -av ./public/ user@example.com:/var/www/site/
 
# リモートからローカルへ
rsync -av user@example.com:/var/www/site/ ./site-backup/

パスを/から書かなければ、リモートのホームディレクトリからの相対パスになります。user@example.com:backup/は~/backup/です。

転送元と転送先の両方をリモートにすることはできません。その場合は、どちらかのサーバーにログインしてから実行します。

なお、ホスト::モジュールのようにコロンを2つ書く形とrsync://のURLは、SSHではなくrsyncデーモン(既定のポートは873)へ直接つなぐ書式です。公開ミラーの取得などで使われますが、この記事ではSSH経由だけを扱います。

よく使うオプション

-a(--archive)は -rlptgoD の束

-aは、manページに「-rlptgoDと同じ」と書かれている、まとめ用のオプションです。

オプション長い名前意味
-r--recursiveディレクトリの中を再帰的に処理する
-l--linksシンボリックリンクをリンクのままコピーする
-p--permsパーミッションを保つ
-t--times更新時刻を保つ
-g--groupグループを保つ
-o--owner所有者を保つ(管理者権限が必要)
-D--devices --specialsデバイスファイルと特殊ファイルを保つ

-aに含まれないものもあります。manページは、ACL(-A)、拡張属性(-X)、アクセス時刻(-U)、作成時刻(-N)、ハードリンクの検出と保持(-H)は含まないと明記しています。ハードリンクを多用しているディレクトリを写す場合は-aHのように足します。

この中で特に大事なのは-tです。rsyncは後で説明するとおり、更新時刻を使って「変更が無い」と判断します。-t(または-a)を付けずにコピーすると、転送先のファイルの更新時刻がコピーした時刻になり、次回の実行で全ファイルが転送の対象になります。迷ったら-aを付ける、で問題ありません。

パーミッションや所有者の考え方はLinuxのファイル権限の記事で説明しています。

-v、-z、-h、-P

オプション意味
-v(--verbose)転送したファイル名と、最後に統計を表示する
-z(--compress)転送中のデータを圧縮する
-h(--human-readable)数値を読みやすい単位で表示する
-P--partial --progressと同じ。進捗を表示し、中断したファイルを残す
-n(--dry-run)実際には何も変更せず、何が起きるかだけを表示する
-i(--itemize-changes)変更の内容を1行ずつ記号で表示する

-zは回線が細いときに効きます。圧縮は転送中のデータにかかるだけで、転送先のファイルが圧縮されて保存されるわけではありません。JPEGや動画、zipのようにすでに圧縮されているファイルが中心なら、効果は小さくなります。ローカル同士の転送では付ける意味がありません。圧縮の仕組みはデータ圧縮の記事で扱っています。

実行例を見てみます。次のようなディレクトリを用意しました。

src
├── css
│   └── style.css
├── index.html
├── logs
│   └── app.log
└── notes.txt
$ rsync -av src/ dest2/
Transfer starting: 7 files
./
index.html
notes.txt
css/
css/style.css
logs/
logs/app.log
 
sent 502 bytes  received 126 bytes  102950 bytes/sec
total size is 31  speedup is 0.05

同じコマンドをもう一度実行すると、ファイル名は1つも表示されません。変更が無いので何も転送していないためです。

$ rsync -av src/ dest2/
Transfer starting: 7 files
 
sent 269 bytes  received 20 bytes  93225 bytes/sec
total size is 31  speedup is 0.11

1行目のTransfer startingはopenrsyncの表示です。rsync 3系では、この行の文言が異なります(rsync 3系の出力は、この記事では採取していません)。

大きなファイルに-hPを付けると、進捗が表示されます。

$ rsync -ahP src/big.bin dest/
big.bin
       20971520 100%   69.16MB/s   00:00:00 (xfer#1, to-check=0/1)

末尾スラッシュの有無で結果が変わる

rsyncで最初につまずくのがここです。転送元のディレクトリ名の末尾に/を付けるかどうかで、転送先にできる構造が変わります。

manページの説明は次のとおりです。

ソースの末尾の / は、「このディレクトリの中身をコピーする」という意味で、付けない場合は「このディレクトリを名前ごとコピーする」という意味だと考えられる

(筆者による要約です。)

スラッシュなし: ディレクトリごとコピーされる

$ rsync -av src dest1/
Transfer starting: 7 files
src/
src/index.html
src/notes.txt
src/css/
src/css/style.css
src/logs/
src/logs/app.log
 
$ find dest1 | sort
dest1
dest1/src
dest1/src/css
dest1/src/css/style.css
dest1/src/index.html
dest1/src/logs
dest1/src/logs/app.log
dest1/src/notes.txt

dest1の下にsrcというディレクトリができました。

スラッシュあり: 中身がコピーされる

$ rsync -av src/ dest2/
Transfer starting: 7 files
./
index.html
notes.txt
css/
css/style.css
logs/
logs/app.log
 
$ find dest2 | sort
dest2
dest2/css
dest2/css/style.css
dest2/index.html
dest2/logs
dest2/logs/app.log
dest2/notes.txt

dest2の直下に、srcの中身が並びました。

覚え方と確認方法

書き方結果
rsync -a src dest/dest/src/index.html
rsync -a src/ dest/dest/index.html
rsync -a src/ dest/src/dest/src/index.html(1つ目と同じ結果)

「src/はsrc/*に近い」と覚えると分かりやすいです。ただしsrc/*と書くとシェルがファイル名に展開するため、ドットで始まるファイルが漏れますし、--deleteも期待どおりに働きません。中身を指すときはsrc/と書きます。

この違いは、-vの出力の先頭を見れば分かります。ファイル名がsrc/index.htmlのように転送元のディレクトリ名から始まっていれば「ディレクトリごと」、index.htmlから始まっていれば「中身」です。-nを足して実行すれば、実際にコピーする前に確かめられます。

デプロイで起きやすい失敗は、rsync -a dist user@example.com:/var/www/site/と書いてしまい、/var/www/site/dist/index.htmlができてサイトが表示されない、というものです。さらに--deleteが付いていると、転送先にあった本来のファイルが「転送元に無いファイル」として消されます。

転送先のスラッシュ

転送先の末尾の/は、転送元がディレクトリのときは結果に影響しません。違いが出るのは、単一のファイルを、まだ存在しない場所へコピーするときです。

$ rsync -a src/index.html d1
$ rsync -a src/index.html d2/
$ ls -ld d1 d2
-rw------- 1 user wheel 15 Nov 16 05:03 d1
drwxr-xr-x 3 user wheel 96 Nov 16 05:03 d2

d1はindex.htmlの中身を持つ「d1という名前のファイル」になり、d2/は「d2というディレクトリ」が作られてその中にindex.htmlが入りました。ディレクトリへ入れたいときは、転送先の末尾に/を付けておくと意図がはっきりします。

なお、manページによると、転送先のパスが存在しない場合にrsyncが作るのは最後の1階層だけで、途中の階層が無いとエラーになります。rsync 3.2.3以降には、途中の階層も作る--mkpathがあります(公式のNEWSで確認。手元のopenrsyncのman rsyncには載っていませんでした)。

--delete: 転送元に無いファイルを消す

既定のrsyncは、転送先のファイルを追加・更新するだけで、消すことはありません。転送元で削除したファイルは、転送先に残り続けます。

--deleteを付けると、転送元に無いファイルを転送先から削除し、2つのディレクトリを同じ状態にします。

rsync -av --delete src/ dest/

危険な理由

manページ自身が、--deleteについて「使い方を誤ると危険です。先に--dry-run(-n)で、どのファイルが削除されるかを確かめるのがとても良い考えです」という趣旨の注意を書いています。

事故のパターンは決まっています。

  • 転送元と転送先を逆に書いた: 古い側の内容で新しい側が上書きされ、新しいファイルが消える
  • 転送元が空だった: マウントされていない外付けディスクや、ビルドに失敗して空のdist/を転送元にした
  • 末尾スラッシュを間違えた: 階層が1つずれ、転送先の既存ファイルがすべて「余分なファイル」と見なされた
  • 転送先が広すぎた: /var/www/の下の1サイトだけを更新するつもりで、/var/www/を転送先にした

空のディレクトリを転送元にした場合を、-nで見てみます。

$ mkdir empty
$ rsync -ain --delete empty/ dest/
*deleting logs/app.log
*deleting logs/
*deleting css/style.css
*deleting css/
*deleting same.txt
*deleting notes.txt
*deleting new.txt
*deleting index.html
.d..t.... ./

-nを外して実行すれば、dest/の中身はすべて消えます。rsyncは「転送元と同じ状態にする」という指示を忠実に実行しているだけです。

一方、転送元のパスが存在しない場合はエラーで止まり、削除は行われませんでした。

$ rsync -a --delete nosuch/ dest/
rsync(11490): error: nosuch/: (l)stat: No such file or directory
$ echo $?
23

危ないのは「存在するが空」のケースです。シェルスクリプトの中でrsync -a --delete "$SRC/" "$DEST/"と書いていて、変数SRCが空だった場合は、転送元が/になります。スクリプトではset -uで未定義の変数をエラーにしておくと、この種の事故を減らせます。詳しくはset -euo pipefailの記事を参照してください。

削除のタイミングを決めるオプション

--deleteには、いつ削除するかを決める仲間のオプションがあります。

オプション削除のタイミング
--delete-before転送を始める前に削除する
--delete-during(--del)転送しながら、ディレクトリごとに削除する
--delete-delay転送中に削除対象を見つけておき、転送が終わってから削除する
--delete-after転送が終わってから、もう一度走査して削除する

manページによると、タイミングを指定しない--deleteは、相手がrsync 3.0.0(2008年3月)以降なら--delete-during、それより古ければ--delete-beforeとして動きます。

使い分けの目安は次のとおりです。

  • 転送先の空き容量が少なく、先に消して空けたい: --delete-before
  • 公開中のサイトで、新しいファイルが揃う前に古いファイルが消えるのを避けたい: --delete-delayか--delete-after
  • 特に理由が無い: 既定のまま

--delete-excluded と --max-delete

--excludeで除外したファイルは、既定では削除の対象からも外れます。manページの言い方では、除外ルールは送信側でファイルを「隠す」効果と、受信側でファイルを「保護する」効果の両方を持ちます。転送先にだけあるlogs/を--exclude='logs/'で除外しておけば、--deleteを付けてもlogs/は消えません。サーバー側で生成されるアップロードファイルやキャッシュを守るときに使う性質です。

--delete-excludedを付けると、この保護が外れ、除外したファイルも転送先から削除されます(manページの説明による)。「除外したものは転送先に存在してほしくない」場合に使うオプションで、--excludeと--deleteを組み合わせる普通の使い方とは意味が逆になるので、取り違えないようにしてください。

なお、手元のopenrsyncで--delete-excluded --exclude='logs/'を試したところ、転送先のlogs/は削除されませんでした。manページの説明どおりに動くかどうかは実装とバージョンによって違う可能性があります。このオプションに頼る場合は、使う環境で必ず-nを付けて確かめてください。

削除の件数に上限を付ける--max-delete=NUMもあります。上限を超えると、それ以降の削除をやめて、終了コード25で終わります。

$ rsync -ai --delete --max-delete=2 src/ dest/
*deleting e3
*deleting e2
Deletions stopped due to --max-delete limit (1 skipped)
$ echo $?
25

定期実行するバックアップで「一度に大量に消えるのはおかしい」という前提があるなら、保険として付けておけます。

-n(--dry-run)と -i で実行前に確かめる

-n(--dry-run)は、実際には何も変更せずに、実行した場合とほぼ同じ出力を表示するオプションです。-vか-iと組み合わせて使います。

-avn の出力

転送元にnew.txtを追加し、転送先にだけold.txtとtmp/cache.datがある状態で実行します。

$ rsync -avn --delete src/ dest/
Transfer starting: 8 files
deleting tmp/cache.dat
deleting tmp/
deleting old.txt
new.txt
 
sent 317 bytes  received 32 bytes  34554 bytes/sec
total size is 35  speedup is 0.10

deletingで始まる行が削除されるファイル、それ以外が転送されるファイルです。--deleteを付けるときは、このdeletingの行を必ず読みます。想定していないファイルが1つでも並んでいたら、コマンドのどこかが間違っています。

-nを付けた実行のあとで転送先を見ると、何も変わっていません。

$ ls dest
css  index.html  logs  notes.txt  old.txt  tmp

-i(--itemize-changes)の出力

-vはファイル名しか表示しないので、「なぜそのファイルが対象になったのか」は分かりません。-iを付けると、理由が記号で表示されます。

今度は、転送元と転送先に次のような違いを作りました。

  • css/style.cssの内容を書き換えた(サイズが変わった)
  • notes.txtの更新時刻だけを変えた
  • index.htmlのパーミッションを600にした
  • new.txtを転送元に追加した
  • 転送先にだけold.txtとtmp/cache.datがある
$ rsync -ain --delete src/ dest/
*deleting tmp/cache.dat
*deleting tmp/
*deleting old.txt
.d..t.... ./
.f...p... index.html
>f+++++++ new.txt
>f..t.... notes.txt
>f.st.... css/style.css

先頭の記号列は、1文字目が「何をするか」、2文字目が「ファイルの種類」、3文字目以降が「どの属性が違うか」です。

位置文字意味
1文字目>ファイルを受け取る(ローカルへ転送される)
1文字目<ファイルを送る(リモートへ転送される)
1文字目cディレクトリの作成など、ローカルでの作成・変更
1文字目.中身は転送しない(属性だけ変わる場合がある)
1文字目*続きがメッセージ(*deletingなど)
2文字目f d Lファイル、ディレクトリ、シンボリックリンク
3文字目cチェックサムが違う(-cを付けたとき)
4文字目sサイズが違う
5文字目t更新時刻が違う
6文字目pパーミッションが違う
7文字目o所有者が違う
8文字目gグループが違う

属性の位置が.なら変更なし、+が並んでいれば新規作成です。上の出力は次のように読めます。

  • .f...p... index.html: 中身は送らず、パーミッションだけを合わせる
  • >f+++++++ new.txt: 新しいファイルとして転送する
  • >f..t.... notes.txt: 更新時刻が違うので転送する(サイズは同じ)
  • >f.st.... css/style.css: サイズと更新時刻が違うので転送する
  • *deleting old.txt: 転送先から削除する

manページ(3.5.2)は、この記号列を11文字(YXcstpoguax)と説明しています。後ろの3文字はアクセス時刻または作成時刻、ACL、拡張属性です。筆者の環境の出力は9文字でしたが、8文字目までの読み方は同じです。

問題が無ければ、-nを外して実行します。

$ rsync -ai --delete src/ dest/
*deleting tmp/cache.dat
*deleting tmp/
*deleting old.txt
.d..t.... ./
.f...p... index.html
>f+++++++ new.txt
>f..t.... notes.txt
>f.st.... css/style.css

dry-runと同じ内容が、今度は実際に行われました。

除外と包含: --exclude、--include、--exclude-from

--exclude

$ rsync -avn --exclude='logs/' --exclude='*.txt' src/ dest4/
Transfer starting: 4 files
./
index.html
css/
css/style.css

logs/ディレクトリと、.txtで終わるファイルが対象から外れました。--excludeは1つにつき1パターンで、複数あるときは繰り返して書きます。パターンはシェルに展開されないよう、引用符で囲みます。

パターンの規則

manページの「PATTERN MATCHING RULES」から、よく使う規則を抜き出します。

パターン意味
*.log名前が.logで終わるもの(どの階層でも)
logs/logsという名前のディレクトリ(末尾の/はディレクトリだけに一致)
/logs/転送の起点の直下にあるlogsディレクトリだけ(先頭の/は起点に固定)
cache/tmp/を含むパターンは、パス全体に対して照合される

先頭の/は、ファイルシステムのルートではなく転送の起点を指します。rsync -a src/ dest/ならsrc/の直下です。実際に試すと、/logs/で除外されるのは直下のlogs/だけで、sub/logs/は転送の対象に残りました。

$ rsync -avn --exclude='/logs/' src/ dz/ | grep -i log
sub/logs/
sub/logs/b.log

--include と順番

manページによると、ルールは書いた順に評価され、最初に一致したものが使われます。そのため、--includeと--excludeを組み合わせるときは順番が意味を持ちます。

「HTMLファイルだけを転送する」例です。

$ rsync -avn --include='*/' --include='*.html' --exclude='*' src/ dest4/
Transfer starting: 4 files
./
index.html
css/
logs/
  • --include='*/': すべてのディレクトリを対象にする(中へ降りていくために必要)
  • --include='*.html': HTMLファイルを対象にする
  • --exclude='*': 残りはすべて除外する

順番を逆にして--exclude='*'を先に書くと、すべてが最初のルールに一致して除外され、何も転送されません。

$ rsync -avn --exclude='*' --include='*.html' src/ dest4/
Transfer starting: 1 files
./

1つ目の例では、中身が空になるcss/とlogs/も作られます。空のディレクトリを作りたくなければ-m(--prune-empty-dirs)を足します(manページに記載のオプションで、この記事では実行していません)。

--exclude-from

除外するものが増えてきたら、ファイルにまとめます。1行に1パターンで、空行と#で始まる行は無視されます。

logs/
*.txt
# comment
$ rsync -avn --exclude-from=ex.txt src/ dest4/
Transfer starting: 4 files
./
index.html
css/
css/style.css

Webサイトのデプロイなら、次のような除外リストをリポジトリに置いておくと、コマンドが短くなり、除外の内容もレビューできます。

.git/
.DS_Store
node_modules/
.env
*.log

変更判定の仕組み

既定は「サイズと更新時刻」の quick check

rsyncは、転送するかどうかをファイルごとに判断します。manページによると、既定ではサイズか更新時刻が違うファイルを転送の対象にします。これを「quick check」と呼びます。ファイルの中身は読まないので、数万ファイルあっても判定はすぐに終わります。

裏を返すと、サイズと更新時刻が同じなら、中身が違っていても転送されません。実際に、転送先のファイルを同じサイズの別の内容に書き換え、更新時刻を転送元と揃えて試しました。

$ printf 'AAAA\n' > src/same.txt
$ rsync -a src/ dest/
$ printf 'BBBB\n' > dest/same.txt
$ touch -r src/same.txt dest/same.txt
$ ls -l src/same.txt dest/same.txt
-rw-r--r-- 1 user wheel 5 Nov 16 05:03 dest/same.txt
-rw-r--r-- 1 user wheel 5 Nov 16 05:03 src/same.txt
 
$ rsync -ain src/ dest/
$

何も表示されず、same.txtは対象になりませんでした。

-c(--checksum)で中身を比べる

-cを付けると、サイズが同じファイルについてチェックサムを計算し、中身で比較します。

$ rsync -ainc src/ dest/
>fc...... same.txt

3文字目のcは、チェックサムが違うことを表しています。

ただし-cは、転送元と転送先の両方で全ファイルを読むことになるので、ディスクの読み込みが大きく増えます。manページも、大幅に遅くなる場合があると書いています。普段は既定のquick checkを使い、-cは「更新時刻が信用できない」「転送後の検証をしたい」といった場面に限るのが現実的です。

逆方向のオプションもあります。

オプション判定の方法
(既定)サイズと更新時刻
-c(--checksum)サイズとチェックサム
--size-onlyサイズだけ
-I(--ignore-times)判定せず、すべてのファイルを転送の対象にする
-u(--update)転送先のほうが新しいファイルはスキップする

デルタ転送アルゴリズムの概要

転送すると決まったファイルについて、rsyncは「転送先にある古い版」を利用して、送るデータを減らします。作者による技術レポート「The rsync algorithm」の内容を、大まかに書くと次のとおりです。

  1. 受信側が、手元の古いファイルを一定サイズのブロックに区切り、各ブロックについて、計算の軽い弱いチェックサムと、衝突しにくい強いチェックサムを計算して、送信側へ送る
  2. 送信側は、新しいファイルのすべての位置について、受信側のブロックと一致する部分を探す。弱いチェックサムは1バイトずらした値を前の値から高速に求められる(ローリングチェックサム)ので、これが現実的な時間でできる
  3. 送信側は、「受信側のこのブロックを使え」という参照と、一致しなかった部分の生のデータを並べて送る
  4. 受信側は、古いファイルのブロックと届いたデータを組み合わせて、新しいファイルを組み立てる

ブロックの境界に縛られずに一致を探すので、ファイルの先頭に数バイト挿入されただけの変更でも、残りの部分は「一致」として扱えます。実際に使うチェックサムの種類は、rsyncのバージョンによって異なります。

ローカル同士では既定で --whole-file になる

デルタ転送は、ネットワークに流すデータを減らすための仕組みです。manページによると、転送元と転送先がどちらもローカルのパスの場合は、--whole-file(-W)が既定になり、デルタ転送を行わずにファイル全体をコピーします。ローカルでは、差分を計算するよりそのまま書いたほうが速いことが多いためです。

20MBのファイルの末尾に数バイトを追記して、--statsで確かめました。

$ rsync -a --stats src/big.bin dest/
Unmatched data: 20971527 B
Matched data: 0 B
Total sent: 20974207 B
 
$ rsync -a --no-whole-file --stats src/big.bin dest/
Unmatched data: 4319 B
Matched data: 20967216 B
Total sent: 22735 B

(関係する行だけを抜き出しています。2回目の前に、もう一度追記しています。)

既定ではMatched dataが0で、ファイル全体を送っています。--no-whole-fileを付けると、ほとんどがMatched dataになり、送ったのは約22KBでした。リモートとの転送では、この「一致した部分は送らない」動作が既定です。

外付けディスクやNASをマウントしたパスへのコピーも、rsyncから見ればローカル同士です。「rsyncなのに差分転送されていない」と感じたら、これが理由です。ただし、変更の無いファイルをスキップするquick checkはローカルでも働くので、2回目以降が速いことに変わりはありません。

中断・帯域・タイムアウト

--partial と -P

既定では、転送が途中で止まると、rsyncは途中まで書いたファイルを削除します。--partialを付けると、その途中のファイルを残します。次の実行で、残ったファイルを元にして続きを転送できるので、大きなファイルを不安定な回線で送るときに役立ちます。

-Pは--partial --progressをまとめたものです。大きなファイルを送るときは-Pを付けておけば、進捗の表示と中断への備えが同時に得られます。

rsync -avP ./backup.tar.gz user@example.com:/srv/backup/

途中のファイルが本来のファイル名で転送先に置かれるのを避けたい場合は、--partial-dir=.rsync-partialのように、置き場所を別のディレクトリに指定できます。

--bwlimit

--bwlimit=RATEは、転送速度の上限を指定します。manページによると、単位を付けない数値は1024バイト単位(毎秒)として扱われ、--bwlimit=1.5mのように単位と小数も書けます。0は制限なしです。

# 毎秒およそ5MBまでに抑える
rsync -av --bwlimit=5m ./media/ user@example.com:/srv/media/

本番サーバーへ大量のファイルを送るときに、回線やディスクを占有して本来のサービスに影響するのを避けるために使います。

--timeout

--timeout=SECONDSは、指定した秒数のあいだデータのやり取りが無ければ、rsyncを終了させます。manページによると既定値は0で、タイムアウトしません。

rsync -av --timeout=120 ./public/ user@example.com:/var/www/site/

cronなどで定期実行する場合、回線の不調で止まったrsyncが残り続け、次の回と重なるのを防ぐために付けておきます。定期実行の書き方はcronの記事で扱っています。

--contimeoutという似た名前のオプションもありますが、こちらはrsyncデーモンへの接続のタイムアウトです。SSH経由の接続のタイムアウトは、SSH側のConnectTimeoutで指定します。

SSH のポートや鍵を指定する

-e でリモートシェルを指定する

-e(--rsh)は、リモートとの接続に使うコマンドを指定します。SSHのオプションを渡したいときは、ここにsshコマンドごと書きます。

# ポートを指定する
rsync -av -e 'ssh -p 2222' ./public/ user@example.com:/var/www/site/
 
# 鍵も指定する
rsync -av -e 'ssh -p 2222 -i ~/.ssh/id_ed25519_deploy' ./public/ user@example.com:/var/www/site/

scpの-Pのような、ポートを直接指定する短いオプションはrsyncにはありません。rsyncの--portはrsyncデーモン用のポートで、SSHのポートには効きません。

~/.ssh/config と併用する

rsyncは内部でsshコマンドを呼ぶので、~/.ssh/configの設定がそのまま効きます。接続先ごとの設定は、そちらに書いておくほうが楽です。

Host web
    HostName example.com
    User deploy
    Port 2222
    IdentityFile ~/.ssh/id_ed25519_deploy
    IdentitiesOnly yes
rsync -av ./public/ web:/var/www/site/

踏み台を経由するProxyJumpも、設定に書いてあればrsyncから意識せずに使えます。書き方はSSH configの記事に、鍵認証の仕組みはSSHの仕組みの記事にまとめています。

リモート側で権限が必要な場合

転送先が一般ユーザーでは書き込めない場所の場合、--rsync-pathでリモート側のrsyncの起動方法を変えられます。

rsync -av --rsync-path='sudo rsync' ./conf/ user@example.com:/etc/myapp/

これは、リモート側でパスワードなしにsudo rsyncを実行できる設定になっていることが前提です(書式の例で、この記事では実行していません)。権限を広く与えることになるので、デプロイ先のディレクトリの所有者を調整して、sudoを使わずに済ませるほうが安全です。

毎日のバックアップを日付ごとのディレクトリに残したい。しかし毎日フルコピーすると、ディスクがすぐに埋まります。--link-destは、この問題をハードリンクで解決します。

--link-dest=DIRを指定すると、rsyncは転送先に新しいディレクトリを作るときに、DIRにある同じファイル(変更されていないファイル)を、コピーする代わりにハードリンクとして置きます。変更されたファイルだけが、新しく書き込まれます。

$ rsync -a src/ bk/2026-11-15/
 
(notes.txt を書き換える)
 
$ rsync -a --link-dest=../2026-11-15 src/ bk/2026-11-16/

--link-destに相対パスを書いた場合は、転送先のディレクトリからの相対パスとして解釈されます。上の../2026-11-15はbk/2026-11-16/から見たパスです。迷うなら絶対パスで書きます。

結果を見てみます。ls -liの先頭の数字はinode番号です。

$ ls -li bk/2026-11-15/index.html bk/2026-11-16/index.html \
         bk/2026-11-15/notes.txt  bk/2026-11-16/notes.txt
398353867 -rw------- 2 user wheel 15 Nov 16 05:03 bk/2026-11-15/index.html
398353869 -rw-r--r-- 1 user wheel  5 Nov 16 05:03 bk/2026-11-15/notes.txt
398353867 -rw------- 2 user wheel 15 Nov 16 05:03 bk/2026-11-16/index.html
398353889 -rw-r--r-- 1 user wheel  8 Nov 16 05:03 bk/2026-11-16/notes.txt
 
$ du -sh bk/2026-11-15 bk/2026-11-16
 24K	bk/2026-11-15
4.0K	bk/2026-11-16

変更していないindex.htmlは、2つの世代でinode番号が同じで、リンク数が2になっています。同じ実体を2つの名前で指しているので、ディスクは1つ分しか使いません。書き換えたnotes.txtは別のinodeです。duで見ると、2世代目が新しく使った容量は変更分だけです。

それでいて、bk/2026-11-16/を開けば、その日の全ファイルが普通のディレクトリとして見えます。復元は、必要な世代のディレクトリからコピーするだけです。古い世代をrm -rfで消しても、ほかの世代から同じ実体が参照されていれば、データは残ります。ハードリンクとinodeの関係はファイルシステムの記事で説明しています。

日次のスクリプトにすると、次のような形になります(書式の例で、この記事では実行していません)。

#!/bin/bash
set -euo pipefail
 
SRC="$HOME/project/"
DEST_ROOT="/Volumes/Backup/project"
TODAY="$(date +%Y-%m-%d)"
 
rsync -a --delete \
  --link-dest="$DEST_ROOT/latest" \
  "$SRC" "$DEST_ROOT/$TODAY/"
 
# latest を今回の世代に付け替える
ln -sfn "$DEST_ROOT/$TODAY" "$DEST_ROOT/latest"

注意点は次のとおりです。

  • ハードリンクは同じファイルシステムの中でしか作れない。--link-destのディレクトリと転送先は、同じディスク(同じボリューム)に置く
  • manページによると、ファイルは保持する属性(パーミッションや所有者など)まで同じでないとリンクされない。リンクされずに毎回コピーされる場合は、属性の違いを疑う
  • ハードリンクで共有されているファイルは実体が1つなので、バックアップの中のファイルを直接編集すると、すべての世代が書き換わる。バックアップは読むだけにする
  • 同じディスクの中の世代管理であり、ディスクが壊れれば全世代を失う。別の媒体へのコピーは別途必要

macOS 標準の rsync の事情

macOSでrsync --versionを実行すると、Linuxとは違う表示になります。

$ rsync --version
openrsync: protocol version 29
rsync version 2.6.9 compatible

macOS 27.2の/usr/bin/rsyncは、openrsyncという別の実装です。man rsyncで表示されるマニュアルも、表題がOPENRSYNC(1)になっています。

openrsync とは

openrsyncのREADMEは、自身を「BSD(ISC)ライセンスのrsyncの実装」と説明しています。OpenBSD向けのRPKI検証ツールであるrpki-clientプロジェクトの一部として書かれたもので、公式にサポートするOSはOpenBSDです。また、対応しているのはrsyncのコマンドライン引数の一部だけだとも書かれています。同じREADMEには、Appleがopenrsyncのフォークに多くの作業を投じてきた、という記述もあります。

2.6.9 から openrsync へ

Appleが公開しているソース(GitHubのapple-oss-distributions)で、macOSの各リリースに対応するrsyncのソースを確認すると、次のことが分かります。

macOSrsyncのソースのタグ内容
14.5rsync-62rsync 2.6.9のソースだけ(configure.inにRSYNC_VERSION=2.6.9)。openrsyncは含まれない
15.0rsync-91.0.6openrsyncディレクトリが加わる。2つの実装のどちらを使うかを選ぶラッパー(rsync.wrapper.c)がある
15.4rsync-146ラッパーのファイルが無くなっている

つまり、長く同梱されていたのはrsync 2.6.9で、macOS 15.0でopenrsyncが加わり、macOS 15.4のソースからは2つを切り替えるラッパーが無くなっています。Apple Developer Forumsでは、2025年4月にAppleのDTSエンジニアが「macOS 15.4には、組み込みのrsyncへの大きな改訂が含まれる」と回答しています。

Appleが実装を切り替えた理由について、Apple自身による説明は確認できませんでした。公式のNEWSによると、rsyncは3.0.0(2008年3月1日)でライセンスがGPLv3以降になっています。これと関連づける解説記事は多くありますが、Appleの意図については未確認の情報として扱います。

実用上の注意

  • rsync version 2.6.9 compatibleという表示は、互換性を示す文字列であり、rsync 2.6.9そのものではない
  • rsync 3系のmanページに載っているオプションが、すべて使えるとは限らない。使えるオプションはman rsyncで確かめる
  • この記事で使った-a、-v、-n、-i、-c、-P、--delete、--max-delete、--exclude、--include、--exclude-from、--link-dest、--stats、--no-whole-fileは、macOS 27.2のopenrsyncで動作した
  • --delete-excludedは、前述のとおりmanページ(rsync 3.5.2)の説明と違う結果になった

本家のrsyncを使いたい場合は、Homebrewで入れられます。執筆時点のHomebrewのrsyncは3.5.2です。

brew install rsync

インストール後は、which rsyncとrsync --versionで、どちらのrsyncが呼ばれているかを確認してください。cronやlaunchdから実行するスクリプトではPATHが違うことがあるので、フルパスで書いておくと確実です。

よくある失敗と対処

転送先に同じ名前のディレクトリが入れ子でできた

dest/src/src/...のようになった場合は、転送元の末尾の/を付け忘れています。rsync -a src/ dest/src/かrsync -a src dest/のどちらかに統一します。

--delete で消えてほしくないファイルが消えた

転送先にだけ存在するファイル(アップロードされた画像、ログ、.envなど)は、--deleteの対象になります。--excludeで除外しておけば、削除からも保護されます。実行前に-nでdeletingの行を確認する習慣が、いちばんの対策です。

毎回すべてのファイルが転送される

-t(または-a)を付けていないと、転送先の更新時刻が転送元と揃わないため、毎回すべてが対象になります。-aを付けているのに起きる場合は、-iの出力で、どの属性が違うと判定されているかを確認します。tなら時刻、pならパーミッションです。更新時刻の精度が粗いファイルシステム(FATなど)が相手のときは、--modify-window=1で時刻の誤差を許容できます。

所有者が変わってしまう・Operation not permitted が出る

-aに含まれる-o(所有者の保持)は、受信側のrsyncが管理者権限で動いていないと働きません。一般ユーザーで受け取ると、転送先のファイルは受信側でrsyncを動かしたユーザーの所有になります。所有者やグループを保つ必要が無いなら、-rlptDのように必要なものだけを指定するか、--no-o --no-gを足します。

ファイル名の空白や記号でエラーになる

リモートのパスに空白が含まれる場合、手元のシェルとリモートのシェルの両方で解釈されるため、引用が難しくなります。公式のNEWSによると、rsync 3.2.4以降は引数の保護の方法が変わり、扱いやすくなっています。古いrsyncやopenrsyncでは挙動が違う可能性があるので、空白を含むパスは-nで確かめてから実行してください。

リモートで rsync: command not found

リモート側にrsyncが入っていません。インストールするか、パスが通っていない場所にある場合は--rsync-path=/usr/local/bin/rsyncのように指定します。

終了コードを見ていない

rsyncは、一部のファイルが転送できなかった場合に0以外の終了コードを返します。この記事で確認できたものでは、転送元が存在しないときが23、--max-deleteの上限に達したときが25でした。スクリプトでは終了コードを確認し、失敗を見逃さないようにします。出力をログに残す方法はパイプとリダイレクトの記事を参照してください。

オプション早見表

オプション意味
-a-rlptgoDの束。再帰し、リンク・権限・時刻・所有者などを保つ
-v転送したファイル名を表示する
-n(--dry-run)何も変更せず、結果だけを表示する
-i(--itemize-changes)変更の内容を記号で表示する
-z転送中のデータを圧縮する
-h数値を読みやすく表示する
-P--partial --progress
-cチェックサムで比較する
-u転送先のほうが新しいファイルをスキップする
-Hハードリンクを保つ(-aには含まれない)
-e 'ssh ...'リモートシェルのコマンドを指定する
--delete転送元に無いファイルを転送先から削除する
--delete-afterほか削除のタイミングを指定する
--delete-excluded除外したファイルも転送先から削除する
--max-delete=NUM削除する件数の上限
--exclude=PATTERN一致するものを除外する
--include=PATTERN一致するものを対象にする(順番に注意)
--exclude-from=FILE除外パターンをファイルから読む
--partial中断したファイルを残す
--bwlimit=RATE転送速度の上限
--timeout=SECONDS通信が無い状態でのタイムアウト(既定は0で無効)
--link-dest=DIR変更の無いファイルをDIRへのハードリンクにする
--stats転送の統計を表示する
--no-whole-fileローカル同士でもデルタ転送を使う
--rsync-path=PROGRAMリモート側で起動するrsyncを指定する

まとめ

  • rsyncは、サイズと更新時刻が同じファイルをスキップし、転送するファイルも差分だけを送る
  • -aは-rlptgoDの束。更新時刻を保つ-tが含まれていることが、2回目以降の速さの前提になる
  • 転送元の末尾の/は「中身」を意味する。付けなければディレクトリごとコピーされ、階層が1つ増える
  • --deleteは転送元に無いファイルを消す。転送元が空だったり階層がずれたりすると、転送先が消える
  • --deleteを付けるときは、先に-nを足してdeletingの行を読む。理由まで知りたいときは-i
  • --excludeしたファイルは、既定では削除からも保護される。ルールは書いた順に評価され、最初に一致したものが使われる
  • 中身で比較したいときは-c。ただし全ファイルを読むので遅い
  • ローカル同士の転送では既定で--whole-fileになり、デルタ転送は行われない
  • 大きなファイルには-P、本番への転送には--bwlimit、定期実行には--timeout
  • SSHのポートや鍵は-e 'ssh -p ...'か、~/.ssh/configで指定する
  • --link-destで、変更の無いファイルをハードリンクにした世代バックアップが作れる
  • macOS標準のrsyncはopenrsyncで、rsync 3系とは使えるオプションや挙動が違う場合がある

まずはrsync -avn src/ dest/で出力を眺めるところから始め、問題が無ければ-nを外す。この順番を守るだけで、rsyncの事故の大半は防げます。オプションの細かい挙動は、使っている環境のman rsyncで確かめてください。

関連記事

参考リンク

lftp で SFTP サーバーに接続する - 鍵認証・ポート指定・mirror での同期まで

lftp で SFTP サーバーに接続する - 鍵認証・ポート指定・mirror での同期まで

約13分

コマンドラインの高機能ファイル転送クライアント lftp で SFTP サーバーに接続する方法を、基本の sftp:// URL、パスワード/公開鍵認証、ポート番号や踏み台の指定、ホスト鍵の確認、mirror での一括ダウンロード/アップロード、リトライやタイムアウトの設定、bash スクリプトでの自動化まで実例つきで解説します。lftp の SFTP は内部で ssh を呼ぶ(sftp:connect-program)ため、ssh の設定や鍵がそのまま効くのがポイントです。

楽天市場のおすすめPR / 楽天アフィリエイト