Man Page of Rsync

ConIenI-Iype: IexI/hImI
rsync
SecIion: (1)
UpdaIed: 23 Sep 2011
!ndex ReIurn Io Main ConIenIs
NAML
rsync - a IasI, versaIiIe, remoIe (and IocaI) IiIe-copying IooI
SYNOPSIS
Local. rsync |0PTT0N...] SRC... |0EST]
Access v1a remole shell.
Pull. rsync |0PTT0N...] |uSER@]R0ST.SRC... |0EST]
Push. rsync |0PTT0N...] SRC... |uSER@]R0ST.0EST
Access v1a rsync daemon.
Pull. rsync |0PTT0N...] |uSER@]R0ST..SRC... |0EST]
rsync |0PTT0N...] rsync.11|uSER@]R0ST|.P0RT]1SRC... |0EST]
Push. rsync |0PTT0N...] SRC... |uSER@]R0ST..0EST
rsync |0PTT0N...] SRC... rsync.11|uSER@]R0ST|.P0RT]10EST
Usages wiIh |usI one SRC arg and no DST arg wiII IisI Ihe source IiIes insIead oI copying.
DLSCRIPTION
Rsync is a IasI and exIraordinariIy versaIiIe IiIe copying IooI. !I can copy IocaIIy, Io/Irom
anoIher hosI over any remoIe sheII, or Io/Irom a remoIe rsync daemon. !I oIIers a Iarge
number oI opIions IhaI conIroI every aspecI oI iIs behavior and permiI very IIexibIe
speciIicaIion oI Ihe seI oI IiIes Io be copied. !I is Iamous Ior iIs deIIa-IransIer aIgoriIhm,
which reduces Ihe amounI oI daIa senI over Ihe neIwork by sending onIy Ihe diIIerences
beIween Ihe source IiIes and Ihe exisIing IiIes in Ihe desIinaIion. Rsync is wideIy used Ior
backups and mirroring and as an improved copy command Ior everyday use.
Rsync Iinds IiIes IhaI need Io be IransIerred using a "guick check" aIgoriIhm (by deIauII)
IhaI Iooks Ior IiIes IhaI have changed in size or in IasI-modiIied Iime. Any changes in Ihe
oIher preserved aIIribuIes (as reguesIed by opIions) are made on Ihe desIinaIion IiIe
direcIIy when Ihe guick check indicaIes IhaI Ihe IiIe's daIa does noI need Io be updaIed.
Some oI Ihe addiIionaI IeaIures oI rsync are:
Man page oI rsync IiIe:///home/pIayers/sIeI/IoIo.hImI
1 sur SS 23/03/2013 17:4S
o
supporI Ior copying Iinks, devices, owners, groups, and permissions
o
excIude and excIude-Irom opIions simiIar Io CNU Iar
o
a CVS excIude mode Ior ignoring Ihe same IiIes IhaI CVS wouId ignore
o
can use any IransparenI remoIe sheII, incIuding ssh or rsh
o
does noI reguire super-user priviIeges
o
pipeIining oI IiIe IransIers Io minimize IaIency cosIs
o
supporI Ior anonymous or auIhenIicaIed rsync daemons (ideaI Ior mirroring)
GLNLRAL
Rsync copies IiIes eiIher Io or Irom a remoIe hosI, or IocaIIy on Ihe currenI hosI (iI does noI
supporI copying IiIes beIween Iwo remoIe hosIs).
There are Iwo diIIerenI ways Ior rsync Io conIacI a remoIe sysIem: using a remoIe-sheII
program as Ihe IransporI (such as ssh or rsh) or conIacIing an rsync daemon direcIIy via
TCP. The remoIe-sheII IransporI is used whenever Ihe source or desIinaIion paIh conIains a
singIe coIon (:) separaIor aIIer a hosI speciIicaIion. ConIacIing an rsync daemon direcIIy
happens when Ihe source or desIinaIion paIh conIains a doubIe coIon (::) separaIor aIIer a
hosI speciIicaIion, OR when an rsync:// URL is speciIied (see aIso Ihe "US!NC RSYNC-
DAMON ATURS V!A A RMOT-SHLL CONNCT!ON" secIion Ior an excepIion Io Ihis
IaIIer ruIe).
As a speciaI case, iI a singIe source arg is speciIied wiIhouI a desIinaIion, Ihe IiIes are IisIed
in an ouIpuI IormaI simiIar Io "Is -I".
As expecIed, iI neiIher Ihe source or desIinaIion paIh speciIy a remoIe hosI, Ihe copy occurs
IocaIIy (see aIso Ihe --list-only opIion).
Rsync reIers Io Ihe IocaI side as Ihe "cIienI" and Ihe remoIe side as Ihe "server". Don'I
conIuse "server" wiIh an rsync daemon -- a daemon is aIways a server, buI a server can be
eiIher a daemon or a remoIe-sheII spawned process.
SLTUP
See Ihe IiIe RADM Ior insIaIIaIion insIrucIions.
Once insIaIIed, you can use rsync Io any machine IhaI you can access via a remoIe sheII (as
2 sur SS 23/03/2013 17:4S
weII as some IhaI you can access using Ihe rsync daemon-mode proIocoI). or remoIe
IransIers, a modern rsync uses ssh Ior iIs communicaIions, buI iI may have been conIigured
Io use a diIIerenI remoIe sheII by deIauII, such as rsh or remsh.
You can aIso speciIy any remoIe sheII you Iike, eiIher by using Ihe -e command Iine opIion,
or by seIIing Ihe RSYNC_RSH environmenI variabIe.
NoIe IhaI rsync musI be insIaIIed on boIh Ihe source and desIinaIion machines.
USAGL
You use rsync in Ihe same way you use rcp. You musI speciIy a source and a desIinaIion, one
oI which may be remoIe.
Perhaps Ihe besI way Io expIain Ihe synIax is wiIh some exampIes:
rsync -l *.c ioo.src1
This wouId IransIer aII IiIes maIching Ihe paIIern ".c Irom Ihe currenI direcIory Io Ihe
direcIory src on Ihe machine Ioo. !I any oI Ihe IiIes aIready exisI on Ihe remoIe sysIem Ihen
Ihe rsync remoIe-updaIe proIocoI is used Io updaIe Ihe IiIe by sending onIy Ihe diIIerences.
See Ihe Iech reporI Ior deIaiIs.
rsync -avz ioo.src1bar 1dala1lmp
This wouId recursiveIy IransIer aII IiIes Irom Ihe direcIory src/bar on Ihe machine Ioo inIo
Ihe /daIa/Imp/bar direcIory on Ihe IocaI machine. The IiIes are IransIerred in "archive"
mode, which ensures IhaI symboIic Iinks, devices, aIIribuIes, permissions, ownerships, eIc.
are preserved in Ihe IransIer. AddiIionaIIy, compression wiII be used Io reduce Ihe size oI
daIa porIions oI Ihe IransIer.
rsync -avz ioo.src1bar1 1dala1lmp
A IraiIing sIash on Ihe source changes Ihis behavior Io avoid creaIing an addiIionaI
direcIory IeveI aI Ihe desIinaIion. You can Ihink oI a IraiIing / on a source as meaning "copy
Ihe conIenIs oI Ihis direcIory" as opposed Io "copy Ihe direcIory by name", buI in boIh cases
Ihe aIIribuIes oI Ihe conIaining direcIory are IransIerred Io Ihe conIaining direcIory on Ihe
desIinaIion. !n oIher words, each oI Ihe IoIIowing commands copies Ihe IiIes in Ihe same
way, incIuding Iheir seIIing oI Ihe aIIribuIes oI /desI/Ioo:
rsync -av 1src1ioo 1desl
rsync -av 1src1ioo1 1desl1ioo
NoIe aIso IhaI hosI and moduIe reIerences don'I reguire a IraiIing sIash Io copy Ihe conIenIs
oI Ihe deIauII direcIory. or exampIe, boIh oI Ihese copy Ihe remoIe direcIory's conIenIs inIo
"/desI":
rsync -av hosl. 1desl
3 sur SS 23/03/2013 17:4S
rsync -av hosl..module 1desl
You can aIso use rsync in IocaI-onIy mode, where boIh Ihe source and desIinaIion don'I have
a ':' in Ihe name. !n Ihis case iI behaves Iike an improved copy command.
inaIIy, you can IisI aII Ihe (IisIabIe) moduIes avaiIabIe Irom a parIicuIar rsync daemon by
Ieaving oII Ihe moduIe name:
rsync somehosl.mydoma1n.com..
See Ihe IoIIowing secIion Ior more deIaiIs.
ADVANCLD USAGL
The synIax Ior reguesIing muIIipIe IiIes Irom a remoIe hosI is done by speciIying addiIionaI
remoIe-hosI args in Ihe same sIyIe as Ihe IirsI, or wiIh Ihe hosIname omiIIed. or insIance,
aII Ihese work:
rsync -av hosl.i1le1 .i1le2 hosl.i1le{3,4) 1desl1
rsync -av hosl..modname1i1le{1,2) hosl..modname1i1le3 1desl1
rsync -av hosl..modname1i1le1 ..modname1i1le{3,4)
OIder versions oI rsync reguired using guoIed spaces in Ihe SRC, Iike Ihese exampIes:
rsync -av hosl.`d1r11i1le1 d1r21i1le2` 1desl
rsync hosl..`modname1d1r11i1le1 modname1d1r21i1le2` 1desl
This word-spIiIIing sIiII works (by deIauII) in Ihe IaIesI rsync, buI is noI as easy Io use as Ihe
IirsI meIhod.
!I you need Io IransIer a IiIename IhaI conIains whiIespace, you can eiIher speciIy Ihe
--protect-args (-s) opIion, or you'II need Io escape Ihe whiIespace in a way IhaI Ihe remoIe
sheII wiII undersIand. or insIance:
rsync -av hosl.`i1le\ name\ W1lh\ spaces` 1desl
CONNLCTING TO AN RSYNC DALMON
!I is aIso possibIe Io use rsync wiIhouI a remoIe sheII as Ihe IransporI. !n Ihis case you wiII
direcIIy connecI Io a remoIe rsync daemon, IypicaIIy using TCP porI 873. (This obviousIy
reguires Ihe daemon Io be running on Ihe remoIe sysIem, so reIer Io Ihe START!NC AN
RSYNC DAMON TO ACCPT CONNCT!ONS secIion beIow Ior inIormaIion on IhaI.)
Using rsync in Ihis way is Ihe same as using iI wiIh a remoIe sheII excepI IhaI:
o
4 sur SS 23/03/2013 17:4S
you eiIher use a doubIe coIon :: insIead oI a singIe coIon Io separaIe Ihe hosIname Irom
Ihe paIh, or you use an rsync:// URL.
o
Ihe IirsI word oI Ihe "paIh" is acIuaIIy a moduIe name.
o
Ihe remoIe daemon may prinI a message oI Ihe day when you connecI.
o
iI you speciIy no paIh name on Ihe remoIe daemon Ihen Ihe IisI oI accessibIe paIhs on
Ihe daemon wiII be shown.
o
iI you speciIy no IocaI desIinaIion Ihen a IisIing oI Ihe speciIied IiIes on Ihe remoIe
daemon is provided.
o
you musI noI speciIy Ihe --rsh (-e) opIion.
An exampIe IhaI copies aII Ihe IiIes in a remoIe moduIe named "src":
rsync -av hosl..src 1desl
Some moduIes on Ihe remoIe daemon may reguire auIhenIicaIion. !I so, you wiII receive a
password prompI when you connecI. You can avoid Ihe password prompI by seIIing Ihe
environmenI variabIe RSYNC_PASSWORD Io Ihe password you wanI Io use or using Ihe
--password-file opIion. This may be useIuI when scripIing rsync.
WARN!NC: On some sysIems environmenI variabIes are visibIe Io aII users. On Ihose
sysIems using --password-file is recommended.
You may esIabIish Ihe connecIion via a web proxy by seIIing Ihe environmenI variabIe
RSYNC_PROXY Io a hosIname:porI pair poinIing Io your web proxy. NoIe IhaI your web
proxy's conIiguraIion musI supporI proxy connecIions Io porI 873.
You may aIso esIabIish a daemon connecIion using a program as a proxy by seIIing Ihe
environmenI variabIe RSYNC_CONNCT_PROC Io Ihe commands you wish Io run in pIace oI
making a direcI sockeI connecIion. The sIring may conIain Ihe escape "%H" Io represenI Ihe
hosIname speciIied in Ihe rsync command (so use "%%" iI you need a singIe "%" in your
sIring). or exampIe:
exporl RSYNC_C0NNECT_PR00=`ssh proxyhosl nc 7R 873`
rsync -av larelhosl1..module1src1 1desl1
rsync -av rsync..11larelhosl21module1src1 1desl1
The command speciIied above uses ssh Io run nc (neIcaI) on a proxyhosI, which Iorwards aII
daIa Io porI 873 (Ihe rsync daemon) on Ihe IargeIhosI (%H).
USING RSYNC-DALMON FLATURLS VIA A RLMOTL-SHLLL
CONNLCTION
S sur SS 23/03/2013 17:4S
!I is someIimes useIuI Io use various IeaIures oI an rsync daemon (such as named moduIes)
wiIhouI acIuaIIy aIIowing any new sockeI connecIions inIo a sysIem (oIher Ihan whaI is
aIready reguired Io aIIow remoIe-sheII access). Rsync supporIs connecIing Io a hosI using a
remoIe sheII and Ihen spawning a singIe-use "daemon" server IhaI expecIs Io read iIs conIig
IiIe in Ihe home dir oI Ihe remoIe user. This can be useIuI iI you wanI Io encrypI a
daemon-sIyIe IransIer's daIa, buI since Ihe daemon is sIarIed up Iresh by Ihe remoIe user,
you may noI be abIe Io use IeaIures such as chrooI or change Ihe uid used by Ihe daemon.
(or anoIher way Io encrypI a daemon IransIer, consider using ssh Io IunneI a IocaI porI Io a
remoIe machine and conIigure a normaI rsync daemon on IhaI remoIe hosI Io onIy aIIow
connecIions Irom "IocaIhosI".)
rom Ihe user's perspecIive, a daemon IransIer via a remoIe-sheII connecIion uses nearIy
Ihe same command-Iine synIax as a normaI rsync-daemon IransIer, wiIh Ihe onIy excepIion
being IhaI you musI expIiciIIy seI Ihe remoIe sheII program on Ihe command-Iine wiIh Ihe
--rsh=COMMAND opIion. (SeIIing Ihe RSYNC_RSH in Ihe environmenI wiII noI Iurn on Ihis
IuncIionaIiIy.) or exampIe:
rsync -av --rsh=ssh hosl..module 1desl
!I you need Io speciIy a diIIerenI remoIe-sheII user, keep in mind IhaI Ihe user@ preIix in
IronI oI Ihe hosI is speciIying Ihe rsync-user vaIue (Ior a moduIe IhaI reguires user-based
auIhenIicaIion). This means IhaI you musI give Ihe '-I user' opIion Io ssh when speciIying Ihe
remoIe-sheII, as in Ihis exampIe IhaI uses Ihe shorI version oI Ihe --rsh opIion:
rsync -av -e "ssh -l ssh-user" rsync-user@hosl..module 1desl
The "ssh-user" wiII be used aI Ihe ssh IeveI; Ihe "rsync-user" wiII be used Io Iog-in Io Ihe
"moduIe".
STARTING AN RSYNC DALMON TO ACCLPT
CONNLCTIONS
!n order Io connecI Io an rsync daemon, Ihe remoIe sysIem needs Io have a daemon aIready
running (or iI needs Io have conIigured someIhing Iike ineId Io spawn an rsync daemon Ior
incoming connecIions on a parIicuIar porI). or IuII inIormaIion on how Io sIarI a daemon
IhaI wiII handIing incoming sockeI connecIions, see Ihe rsyncd.conf(S) man page -- IhaI is
Ihe conIig IiIe Ior Ihe daemon, and iI conIains Ihe IuII deIaiIs Ior how Io run Ihe daemon
(incIuding sIand-aIone and ineId conIiguraIions).
!I you're using one oI Ihe remoIe-sheII IransporIs Ior Ihe IransIer, Ihere is no need Io
manuaIIy sIarI an rsync daemon.
SORTLD TRANSFLR ORDLR
6 sur SS 23/03/2013 17:4S
Rsync aIways sorIs Ihe speciIied IiIenames inIo iIs inIernaI IransIer IisI. This handIes Ihe
merging IogeIher oI Ihe conIenIs oI idenIicaIIy named direcIories, makes iI easy Io remove
dupIicaIe IiIenames, and may conIuse someone when Ihe IiIes are IransIerred in a diIIerenI
order Ihan whaI was given on Ihe command-Iine.
!I you need a parIicuIar IiIe Io be IransIerred prior Io anoIher, eiIher separaIe Ihe IiIes inIo
diIIerenI rsync caIIs, or consider using --delay-updates (which doesn'I aIIecI Ihe sorIed
IransIer order, buI does make Ihe IinaI IiIe-updaIing phase happen much more rapidIy).
LXAMPLLS
Here are some exampIes oI how ! use rsync.
To backup my wiIe's home direcIory, which consisIs oI Iarge MS Word IiIes and maiI IoIders,
! use a cron |ob IhaI runs
rsync -Cavz . arv1dsaur.backup
each nighI over a PPP connecIion Io a dupIicaIe direcIory on my machine "arvids|aur".
To synchronize my samba source Irees ! use Ihe IoIIowing MakeIiIe IargeIs:
el.
rsync -avuzb --exclude `*~` samba.samba1 .
pul.
rsync -Cavuzb . samba.samba1
sync. el pul
Ihis aIIows me Io sync wiIh a CVS direcIory aI Ihe oIher end oI Ihe connecIion. ! Ihen do CVS
operaIions on Ihe remoIe machine, which saves a IoI oI Iime as Ihe remoIe CVS proIocoI isn'I
very eIIicienI.
! mirror a direcIory beIween my "oId" and "new" IIp siIes wiIh Ihe command:
rsync -az -e ssh --delele ~ilp1pub1samba n1mbus."~ilp1pub1lr1de"
This is Iaunched Irom cron every Iew hours.
OPTIONS SUMMARY
Here is a shorI summary oI Ihe opIions avaiIabIe in rsync. PIease reIer Io Ihe deIaiIed
descripIion beIow Ior a compIeIe descripIion.
-v, --verbose 1ncrease verbos1ly
-q, --qu1el suppress non-error messaes
--no-mold suppress daemon-mode M0T0 {see caveal}
7 sur SS 23/03/2013 17:4S
-c, --checksum sk1p based on checksum, nol mod-l1me & s1ze
-a, --arch1ve arch1ve mode, equals -rlplo0 {no -R,-A,-X}
--no-0PTT0N lurn oii an 1mpl1ed 0PTT0N {e.. --no-0}
-r, --recurs1ve recurse 1nlo d1reclor1es
-R, --relal1ve use relal1ve palh names
--no-1mpl1ed-d1rs don`l send 1mpl1ed d1rs W1lh --relal1ve
-b, --backup make backups {see --suii1x & --backup-d1r}
--backup-d1r=0TR make backups 1nlo h1erarchy based 1n 0TR
--suii1x=SuIITX backup suii1x {deiaull ~ W1o --backup-d1r}
-u, --updale sk1p i1les lhal are neWer on lhe rece1ver
--1nplace updale desl1nal1on i1les 1n-place
--append append dala onlo shorler i1les
--append-ver1iy --append W1old dala 1n i1le checksum
-d, --d1rs lransier d1reclor1es W1lhoul recurs1n
-l, --l1nks copy syml1nks as syml1nks
-L, --copy-l1nks lransiorm syml1nk 1nlo reierenl i1le1d1r
--copy-unsaie-l1nks only "unsaie" syml1nks are lransiormed
--saie-l1nks 1nore syml1nks lhal po1nl ouls1de lhe lree
-k, --copy-d1rl1nks lransiorm syml1nk lo d1r 1nlo reierenl d1r
-K, --keep-d1rl1nks lreal syml1nked d1r on rece1ver as d1r
-R, --hard-l1nks preserve hard l1nks
-p, --perms preserve perm1ss1ons
-E, --execulab1l1ly preserve execulab1l1ly
--chmod=CRM00 aiiecl i1le and1or d1reclory perm1ss1ons
-A, --acls preserve ACLs {1mpl1es -p}
-X, --xallrs preserve exlended allr1bules
-o, --oWner preserve oWner {super-user only}
-, --roup preserve roup
--dev1ces preserve dev1ce i1les {super-user only}
--spec1als preserve spec1al i1les
-0 same as --dev1ces --spec1als
-l, --l1mes preserve mod1i1cal1on l1mes
-0, --om1l-d1r-l1mes om1l d1reclor1es irom --l1mes
--super rece1ver allempls super-user acl1v1l1es
--iake-super slore1recover pr1v1leed allrs us1n xallrs
-S, --sparse handle sparse i1les eii1c1enlly
-n, --dry-run periorm a lr1al run W1lh no chanes made
-W, --Whole-i1le copy i1les Whole {W1o della-xier alor1lhm}
-x, --one-i1le-syslem don`l cross i1lesyslem boundar1es
-B, --block-s1ze=STZE iorce a i1xed checksum block-s1ze
-e, --rsh=C0MMAN0 spec1iy lhe remole shell lo use
--rsync-palh=PR00RAM spec1iy lhe rsync lo run on remole mach1ne
--ex1sl1n sk1p creal1n neW i1les on rece1ver
--1nore-ex1sl1n sk1p updal1n i1les lhal ex1sl on rece1ver
--remove-source-i1les sender removes synchron1zed i1les {non-d1r}
--del an al1as ior --delele-dur1n
--delele delele exlraneous i1les irom desl d1rs
--delele-beiore rece1ver deleles beiore xier, nol dur1n
--delele-dur1n rece1ver deleles dur1n lhe lransier
--delele-delay i1nd delel1ons dur1n, delele ailer
--delele-ailer rece1ver deleles ailer lransier, nol dur1n
--delele-excluded also delele excluded i1les irom desl d1rs
--1nore-errors delele even 1i lhere are T10 errors
--iorce iorce delel1on oi d1rs even 1i nol emply
--max-delele=NuM don`l delele more lhan NuM i1les
--max-s1ze=STZE don`l lransier any i1le larer lhan STZE
--m1n-s1ze=STZE don`l lransier any i1le smaller lhan STZE
--parl1al keep parl1ally lransierred i1les
--parl1al-d1r=0TR pul a parl1ally lransierred i1le 1nlo 0TR
--delay-updales pul all updaled i1les 1nlo place al end
8 sur SS 23/03/2013 17:4S
-m, --prune-emply-d1rs prune emply d1reclory cha1ns irom i1le-l1sl
--numer1c-1ds don`l map u1d11d values by user1roup name
--l1meoul=SEC0N0S sel T10 l1meoul 1n seconds
--conl1meoul=SEC0N0S sel daemon connecl1on l1meoul 1n seconds
-T, --1nore-l1mes don`l sk1p i1les lhal malch s1ze and l1me
--s1ze-only sk1p i1les lhal malch 1n s1ze
--mod1iy-W1ndoW=NuM compare mod-l1mes W1lh reduced accuracy
-T, --lemp-d1r=0TR creale lemporary i1les 1n d1reclory 0TR
-y, --iuzzy i1nd s1m1lar i1le ior bas1s 1i no desl i1le
--compare-desl=0TR also compare rece1ved i1les relal1ve lo 0TR
--copy-desl=0TR ... and 1nclude cop1es oi unchaned i1les
--l1nk-desl=0TR hardl1nk lo i1les 1n 0TR When unchaned
-z, --compress compress i1le dala dur1n lhe lransier
--compress-level=NuM expl1c1lly sel compress1on level
--sk1p-compress=LTST sk1p compress1n i1les W1lh suii1x 1n LTST
-C, --cvs-exclude aulo-1nore i1les 1n lhe same Way CvS does
-i, --i1ller=RuLE add a i1le-i1ller1n RuLE
-I same as --i1ller=`d1r-mere 1.rsync-i1ller`
repealed. --i1ller=`- .rsync-i1ller`
--exclude=PATTERN exclude i1les malch1n PATTERN
--exclude-irom=ITLE read exclude pallerns irom ITLE
--1nclude=PATTERN don`l exclude i1les malch1n PATTERN
--1nclude-irom=ITLE read 1nclude pallerns irom ITLE
--i1les-irom=ITLE read l1sl oi source-i1le names irom ITLE
-0, --irom0 all *irom1i1ller i1les are del1m1led by 0s
-s, --prolecl-ars no space-spl1ll1n, W1ldcard chars only
--address=A00RESS b1nd address ior oulo1n sockel lo daemon
--porl=P0RT spec1iy double-colon allernale porl number
--sockopls=0PTT0NS spec1iy cuslom TCP opl1ons
--block1n-1o use block1n T10 ior lhe remole shell
--slals 1ve some i1le-lransier slals
-8, --8-b1l-oulpul leave h1h-b1l chars unescaped 1n oulpul
-h, --human-readable oulpul numbers 1n a human-readable iormal
--proress shoW proress dur1n lransier
-P same as --parl1al --proress
-1, --1lem1ze-chanes oulpul a chane-summary ior all updales
--oul-iormal=I0RMAT oulpul updales us1n lhe spec1i1ed I0RMAT
--lo-i1le=ITLE lo Whal We`re do1n lo lhe spec1i1ed ITLE
--lo-i1le-iormal=IMT lo updales us1n lhe spec1i1ed IMT
--passWord-i1le=ITLE read daemon-access passWord irom ITLE
--l1sl-only l1sl lhe i1les 1nslead oi copy1n lhem
--bWl1m1l=KBPS l1m1l T10 bandW1dlh, KByles per second
--Wr1le-balch=ITLE Wr1le a balched updale lo ITLE
--only-Wr1le-balch=ITLE l1ke --Wr1le-balch bul W1o updal1n desl
--read-balch=ITLE read a balched updale irom ITLE
--prolocol=NuM iorce an older prolocol vers1on lo be used
--1conv=C0NvERT_SPEC requesl charsel convers1on oi i1lenames
--checksum-seed=NuM sel block1i1le checksum seed {advanced}
-4, --1pv4 preier TPv4
--vers1on pr1nl vers1on number
{-h} --help shoW lh1s help {see beloW ior -h commenl}
Rsync can aIso be run as a daemon, in which case Ihe IoIIowing opIions are accepIed:
--daemon run as an rsync daemon
--address=A00RESS b1nd lo lhe spec1i1ed address
--bWl1m1l=KBPS l1m1l T10 bandW1dlh, KByles per second
9 sur SS 23/03/2013 17:4S
--coni1=ITLE spec1iy allernale rsyncd.coni i1le
--no-delach do nol delach irom lhe parenl
--porl=P0RT l1slen on allernale porl number
--lo-i1le=ITLE overr1de lhe "lo i1le" sell1n
--lo-i1le-iormal=IMT overr1de lhe "lo iormal" sell1n
--sockopls=0PTT0NS spec1iy cuslom TCP opl1ons
-v, --verbose 1ncrease verbos1ly
-h, --help shoW lh1s help {1i used ailer --daemon}
OPTIONS
Rsync accepIs boIh Iong (doubIe-dash word) and shorI (singIe-dash IeIIer) opIions. The
IuII IisI oI Ihe avaiIabIe opIions are described beIow. !I an opIion can be speciIied in more
Ihan one way, Ihe choices are comma-separaIed. Some opIions onIy have a Iong varianI, noI
a shorI. !I Ihe opIion Iakes a parameIer, Ihe parameIer is onIy IisIed aIIer Ihe Iong varianI,
even Ihough iI musI aIso be speciIied Ior Ihe shorI. When speciIying a parameIer, you can
eiIher use Ihe Iorm --opIion=param or repIace Ihe '=' wiIh whiIespace. The parameIer may
need Io be guoIed in some manner Ior iI Io survive Ihe sheII's command-Iine parsing. Keep
in mind IhaI a Ieading IiIde (~) in a IiIename is subsIiIuIed by your sheII, so --opIion=~/Ioo
wiII noI change Ihe IiIde inIo your home direcIory (remove Ihe '=' Ior IhaI).
--help
PrinI a shorI heIp page describing Ihe opIions avaiIabIe in rsync and exiI. or
backward-compaIibiIiIy wiIh oIder versions oI rsync, Ihe heIp wiII aIso be ouIpuI iI you
use Ihe -h opIion wiIhouI any oIher args.
--version
prinI Ihe rsync version number and exiI.
-v, --verbose
This opIion increases Ihe amounI oI inIormaIion you are given during Ihe IransIer. 8y
deIauII, rsync works siIenIIy. A singIe -v wiII give you inIormaIion abouI whaI IiIes are
being IransIerred and a brieI summary aI Ihe end. Two -v opIions wiII give you
inIormaIion on whaI IiIes are being skipped and sIighIIy more inIormaIion aI Ihe end.
More Ihan Iwo -v opIions shouId onIy be used iI you are debugging rsync.
NoIe IhaI Ihe names oI Ihe IransIerred IiIes IhaI are ouIpuI are done using a deIauII
--out-format oI "%n%L", which IeIIs you |usI Ihe name oI Ihe IiIe and, iI Ihe iIem is a
Iink, where iI poinIs. AI Ihe singIe -v IeveI oI verbosiIy, Ihis does noI menIion when a
IiIe geIs iIs aIIribuIes changed. !I you ask Ior an iIemized IisI oI changed aIIribuIes
(eiIher --itemize-changes or adding "%i" Io Ihe --out-format seIIing), Ihe ouIpuI (on
Ihe cIienI) increases Io menIion aII iIems IhaI are changed in any way. See Ihe --out-
format opIion Ior more deIaiIs.
-g, --guiet
This opIion decreases Ihe amounI oI inIormaIion you are given during Ihe IransIer,
noIabIy suppressing inIormaIion messages Irom Ihe remoIe server. This opIion is
useIuI when invoking rsync Irom cron.
--no-motd
10 sur SS 23/03/2013 17:4S
This opIion aIIecIs Ihe inIormaIion IhaI is ouIpuI by Ihe cIienI aI Ihe sIarI oI a daemon
IransIer. This suppresses Ihe message-oI-Ihe-day (MOTD) IexI, buI iI aIso aIIecIs Ihe IisI
oI moduIes IhaI Ihe daemon sends in response Io Ihe "rsync hosI::" reguesI (due Io a
IimiIaIion in Ihe rsync proIocoI), so omiI Ihis opIion iI you wanI Io reguesI Ihe IisI oI
moduIes Irom Ihe daemon.
-I, --ignore-times
NormaIIy rsync wiII skip any IiIes IhaI are aIready Ihe same size and have Ihe same
modiIicaIion IimesIamp. This opIion Iurns oII Ihis "guick check" behavior, causing aII
IiIes Io be updaIed.
--size-only
This modiIies rsync's "guick check" aIgoriIhm Ior Iinding IiIes IhaI need Io be
IransIerred, changing iI Irom Ihe deIauII oI IransIerring IiIes wiIh eiIher a changed
size or a changed IasI-modiIied Iime Io |usI Iooking Ior IiIes IhaI have changed in size.
This is useIuI when sIarIing Io use rsync aIIer using anoIher mirroring sysIem which
may noI preserve IimesIamps exacIIy.
--modify-window
When comparing Iwo IimesIamps, rsync IreaIs Ihe IimesIamps as being eguaI iI Ihey
diIIer by no more Ihan Ihe modiIy-window vaIue. This is normaIIy 0 (Ior an exacI
maIch), buI you may Iind iI useIuI Io seI Ihis Io a Iarger vaIue in some siIuaIions. !n
parIicuIar, when IransIerring Io or Irom an MS Windows AT IiIesysIem (which
represenIs Iimes wiIh a 2-second resoIuIion), --modify-window=1 is useIuI (aIIowing
Iimes Io diIIer by up Io 1 second).
-c, --checksum
This changes Ihe way rsync checks iI Ihe IiIes have been changed and are in need oI a
IransIer. WiIhouI Ihis opIion, rsync uses a "guick check" IhaI (by deIauII) checks iI each
IiIe's size and Iime oI IasI modiIicaIion maIch beIween Ihe sender and receiver. This
opIion changes Ihis Io compare a 128-biI checksum Ior each IiIe IhaI has a maIching
size. CeneraIing Ihe checksums means IhaI boIh sides wiII expend a IoI oI disk !/O
reading aII Ihe daIa in Ihe IiIes in Ihe IransIer (and Ihis is prior Io any reading IhaI wiII
be done Io IransIer changed IiIes), so Ihis can sIow Ihings down signiIicanIIy.
The sending side generaIes iIs checksums whiIe iI is doing Ihe IiIe-sysIem scan IhaI
buiIds Ihe IisI oI Ihe avaiIabIe IiIes. The receiver generaIes iIs checksums when iI is
scanning Ior changed IiIes, and wiII checksum any IiIe IhaI has Ihe same size as Ihe
corresponding sender's IiIe: IiIes wiIh eiIher a changed size or a changed checksum are
seIecIed Ior IransIer.
NoIe IhaI rsync aIways veriIies IhaI each trcnsjcrrcd IiIe was correcIIy reconsIrucIed
on Ihe receiving side by checking a whoIe-IiIe checksum IhaI is generaIed as Ihe IiIe is
IransIerred, buI IhaI auIomaIic aIIer-Ihe-IransIer veriIicaIion has noIhing Io do wiIh
Ihis opIion's beIore-Ihe-IransIer "Does Ihis IiIe need Io be updaIed?" check.
or proIocoI 30 and beyond (IirsI supporIed in 3.0.0), Ihe checksum used is MDS. or
oIder proIocoIs, Ihe checksum used is MD4.
-a, --archive
This is eguivaIenI Io -rlptgoD. !I is a guick way oI saying you wanI recursion and wanI
Io preserve aImosI everyIhing (wiIh -H being a noIabIe omission). The onIy excepIion
Io Ihe above eguivaIence is when --files-from is speciIied, in which case -r is noI
impIied.
NoIe IhaI -a does not preserve hardlinks, because Iinding muIIipIy-Iinked IiIes is
expensive. You musI separaIeIy speciIy -H.
11 sur SS 23/03/2013 17:4S
--no-OPT!ON
You may Iurn oII one or more impIied opIions by preIixing Ihe opIion name wiIh "no-".
NoI aII opIions may be preIixed wiIh a "no-": onIy opIions IhaI are impIied by oIher
opIions (e.g. --no-D, --no-perms) or have diIIerenI deIauIIs in various circumsIances
(e.g. --no-whole-file, --no-blocking-io, --no-dirs). You may speciIy eiIher Ihe shorI or
Ihe Iong opIion name aIIer Ihe "no-" preIix (e.g. --no-R is Ihe same as --no-relative).
or exampIe: iI you wanI Io use -a (--archive) buI don'I wanI -o (--owner), insIead oI
converIing -a inIo -rlptgD, you couId speciIy -a --no-o (or -a --no-owner).
The order oI Ihe opIions is imporIanI: iI you speciIy --no-r -a, Ihe -r opIion wouId end
up being Iurned on, Ihe opposiIe oI -a --no-r. NoIe aIso IhaI Ihe side-eIIecIs oI Ihe
--files-from opIion are NOT posiIionaI, as iI aIIecIs Ihe deIauII sIaIe oI severaI opIions
and sIighIIy changes Ihe meaning oI -a (see Ihe --files-from opIion Ior more deIaiIs).
-r, --recursive
This IeIIs rsync Io copy direcIories recursiveIy. See aIso --dirs (-d).
8eginning wiIh rsync 3.0.0, Ihe recursive aIgoriIhm used is now an incremenIaI scan
IhaI uses much Iess memory Ihan beIore and begins Ihe IransIer aIIer Ihe scanning oI
Ihe IirsI Iew direcIories have been compIeIed. This incremenIaI scan onIy aIIecIs our
recursion aIgoriIhm, and does noI change a non-recursive IransIer. !I is aIso onIy
possibIe when boIh ends oI Ihe IransIer are aI IeasI version 3.0.0.
Some opIions reguire rsync Io know Ihe IuII IiIe IisI, so Ihese opIions disabIe Ihe
incremenIaI recursion mode. These incIude: --delete-before, --delete-after, --prune-
empty-dirs, and --delay-updates. 8ecause oI Ihis, Ihe deIauII deIeIe mode when you
speciIy --delete is now --delete-during when boIh ends oI Ihe connecIion are aI IeasI
3.0.0 (use --del or --delete-during Io reguesI Ihis improved deIeIion mode expIiciIIy).
See aIso Ihe --delete-delay opIion IhaI is a beIIer choice Ihan using --delete-after.
!ncremenIaI recursion can be disabIed using Ihe --no-inc-recursive opIion or iIs
shorIer --no-i-r aIias.
-R, --relative
Use reIaIive paIhs. This means IhaI Ihe IuII paIh names speciIied on Ihe command Iine
are senI Io Ihe server raIher Ihan |usI Ihe IasI parIs oI Ihe IiIenames. This is
parIicuIarIy useIuI when you wanI Io send severaI diIIerenI direcIories aI Ihe same
Iime. or exampIe, iI you used Ihis command:
rsync -av 1ioo1bar1baz.c remole.1lmp1
... Ihis wouId creaIe a IiIe named baz.c in /Imp/ on Ihe remoIe machine. !I insIead you
used
rsync -avR 1ioo1bar1baz.c remole.1lmp1
Ihen a IiIe named /Imp/Ioo/bar/baz.c wouId be creaIed on Ihe remoIe machine,
preserving iIs IuII paIh. These exIra paIh eIemenIs are caIIed "impIied direcIories" (i.e.
Ihe "Ioo" and Ihe "Ioo/bar" direcIories in Ihe above exampIe).
8eginning wiIh rsync 3.0.0, rsync aIways sends Ihese impIied direcIories as reaI
direcIories in Ihe IiIe IisI, even iI a paIh eIemenI is reaIIy a symIink on Ihe sending side.
This prevenIs some reaIIy unexpecIed behaviors when copying Ihe IuII paIh oI a IiIe
IhaI you didn'I reaIize had a symIink in iIs paIh. !I you wanI Io dupIicaIe a server-side
symIink, incIude boIh Ihe symIink via iIs paIh, and reIerenI direcIory via iIs reaI paIh.
!I you're deaIing wiIh an oIder rsync on Ihe sending side, you may need Io use Ihe
--no-implied-dirs opIion.
12 sur SS 23/03/2013 17:4S
!I is aIso possibIe Io IimiI Ihe amounI oI paIh inIormaIion IhaI is senI as impIied
direcIories Ior each paIh you speciIy. WiIh a modern rsync on Ihe sending side
(beginning wiIh 2.6.7), you can inserI a doI and a sIash inIo Ihe source paIh, Iike Ihis:
rsync -avR 1ioo1.1bar1baz.c remole.1lmp1
ThaI wouId creaIe /Imp/bar/baz.c on Ihe remoIe machine. (NoIe IhaI Ihe doI musI be
IoIIowed by a sIash, so "/Ioo/." wouId noI be abbreviaIed.) or oIder rsync versions, you
wouId need Io use a chdir Io IimiI Ihe source paIh. or exampIe, when pushing IiIes:
{cd 1ioo, rsync -avR bar1baz.c remole.1lmp1}
(NoIe IhaI Ihe parens puI Ihe Iwo commands inIo a sub-sheII, so IhaI Ihe "cd" command
doesn'I remain in eIIecI Ior IuIure commands.) !I you're puIIing IiIes Irom an oIder
rsync, use Ihis idiom (buI onIy Ior a non-daemon IransIer):
rsync -avR --rsync-palh="cd 1ioo, rsync" \
remole.bar1baz.c 1lmp1
--no-implied-dirs
This opIion aIIecIs Ihe deIauII behavior oI Ihe --relative opIion. When iI is speciIied,
Ihe aIIribuIes oI Ihe impIied direcIories Irom Ihe source names are noI incIuded in Ihe
IransIer. This means IhaI Ihe corresponding paIh eIemenIs on Ihe desIinaIion sysIem
are IeII unchanged iI Ihey exisI, and any missing impIied direcIories are creaIed wiIh
deIauII aIIribuIes. This even aIIows Ihese impIied paIh eIemenIs Io have big
diIIerences, such as being a symIink Io a direcIory on Ihe receiving side.
or insIance, iI a command-Iine arg or a IiIes-Irom enIry IoId rsync Io IransIer Ihe IiIe
"paIh/Ioo/IiIe", Ihe direcIories "paIh" and "paIh/Ioo" are impIied when --relative is
used. !I "paIh/Ioo" is a symIink Io "bar" on Ihe desIinaIion sysIem, Ihe receiving rsync
wouId ordinariIy deIeIe "paIh/Ioo", recreaIe iI as a direcIory, and receive Ihe IiIe inIo
Ihe new direcIory. WiIh --no-implied-dirs, Ihe receiving rsync updaIes "paIh/Ioo/IiIe"
using Ihe exisIing paIh eIemenIs, which means IhaI Ihe IiIe ends up being creaIed in
"paIh/bar". AnoIher way Io accompIish Ihis Iink preservaIion is Io use Ihe --keep-
dirlinks opIion (which wiII aIso aIIecI symIinks Io direcIories in Ihe resI oI Ihe
IransIer).
When puIIing IiIes Irom an rsync oIder Ihan 3.0.0, you may need Io use Ihis opIion iI
Ihe sending side has a symIink in Ihe paIh you reguesI and you wish Ihe impIied
direcIories Io be IransIerred as normaI direcIories.
-b, --backup
WiIh Ihis opIion, preexisIing desIinaIion IiIes are renamed as each IiIe is IransIerred or
deIeIed. You can conIroI where Ihe backup IiIe goes and whaI (iI any) suIIix geIs
appended using Ihe --backup-dir and --suffix opIions.
NoIe IhaI iI you don'I speciIy --backup-dir, (1) Ihe --omit-dir-times opIion wiII be
impIied, and (2) iI --delete is aIso in eIIecI (wiIhouI --delete-excluded), rsync wiII add a
"proIecI" IiIIer-ruIe Ior Ihe backup suIIix Io Ihe end oI aII your exisIing excIudes (e.g. -f
"P *~"). This wiII prevenI previousIy backed-up IiIes Irom being deIeIed. NoIe IhaI iI
you are suppIying your own IiIIer ruIes, you may need Io manuaIIy inserI your own
excIude/proIecI ruIe somewhere higher up in Ihe IisI so IhaI iI has a high enough
prioriIy Io be eIIecIive (e.g., iI your ruIes speciIy a IraiIing incIusion/excIusion oI '"', Ihe
auIo-added ruIe wouId never be reached).
--backup-dir=DIR
13 sur SS 23/03/2013 17:4S
!n combinaIion wiIh Ihe --backup opIion, Ihis IeIIs rsync Io sIore aII backups in Ihe
speciIied direcIory on Ihe receiving side. This can be used Ior incremenIaI backups.
You can addiIionaIIy speciIy a backup suIIix using Ihe --suffix opIion (oIherwise Ihe
IiIes backed up in Ihe speciIied direcIory wiII keep Iheir originaI IiIenames).
NoIe IhaI iI you speciIy a reIaIive paIh, Ihe backup direcIory wiII be reIaIive Io Ihe
desIinaIion direcIory, so you probabIy wanI Io speciIy eiIher an absoIuIe paIh or a paIh
IhaI sIarIs wiIh "../". !I an rsync daemon is Ihe receiver, Ihe backup dir cannoI go
ouIside Ihe moduIe's paIh hierarchy, so Iake exIra care noI Io deIeIe iI or copy inIo iI.
--suffix=SUFFIX
This opIion aIIows you Io override Ihe deIauII backup suIIix used wiIh Ihe --backup
(-b) opIion. The deIauII suIIix is a ~ iI no --backup-dir was speciIied, oIherwise iI is an
empIy sIring.
-u, --update
This Iorces rsync Io skip any IiIes which exisI on Ihe desIinaIion and have a modiIied
Iime IhaI is newer Ihan Ihe source IiIe. (!I an exisIing desIinaIion IiIe has a
modiIicaIion Iime eguaI Io Ihe source IiIe's, iI wiII be updaIed iI Ihe sizes are diIIerenI.)
NoIe IhaI Ihis does noI aIIecI Ihe copying oI symIinks or oIher speciaI IiIes. AIso, a
diIIerence oI IiIe IormaI beIween Ihe sender and receiver is aIways considered Io be
imporIanI enough Ior an updaIe, no maIIer whaI daIe is on Ihe ob|ecIs. !n oIher words,
iI Ihe source has a direcIory where Ihe desIinaIion has a IiIe, Ihe IransIer wouId occur
regardIess oI Ihe IimesIamps.
This opIion is a IransIer ruIe, noI an excIude, so iI doesn'I aIIecI Ihe daIa IhaI goes inIo
Ihe IiIe-IisIs, and Ihus iI doesn'I aIIecI deIeIions. !I |usI IimiIs Ihe IiIes IhaI Ihe receiver
reguesIs Io be IransIerred.
--inplace
This opIion changes how rsync IransIers a IiIe when iIs daIa needs Io be updaIed:
insIead oI Ihe deIauII meIhod oI creaIing a new copy oI Ihe IiIe and moving iI inIo
pIace when iI is compIeIe, rsync insIead wriIes Ihe updaIed daIa direcIIy Io Ihe
desIinaIion IiIe.
This has severaI eIIecIs:
o
Hard Iinks are noI broken. This means Ihe new daIa wiII be visibIe Ihrough
oIher hard Iinks Io Ihe desIinaIion IiIe. Moreover, aIIempIs Io copy diIIering
source IiIes onIo a muIIipIy-Iinked desIinaIion IiIe wiII resuII in a "Iug oI
war" wiIh Ihe desIinaIion daIa changing back and IorIh.
o
!n-use binaries cannoI be updaIed (eiIher Ihe OS wiII prevenI Ihis Irom
happening, or binaries IhaI aIIempI Io swap-in Iheir daIa wiII misbehave or
crash).
o
The IiIe's daIa wiII be in an inconsisIenI sIaIe during Ihe IransIer and wiII be
IeII IhaI way iI Ihe IransIer is inIerrupIed or iI an updaIe IaiIs.
o
A IiIe IhaI rsync cannoI wriIe Io cannoI be updaIed. WhiIe a super user can
updaIe any IiIe, a normaI user needs Io be granIed wriIe permission Ior Ihe
open oI Ihe IiIe Ior wriIing Io be successIuI.
o
The eIIiciency oI rsync's deIIa-IransIer aIgoriIhm may be reduced iI some
14 sur SS 23/03/2013 17:4S
daIa in Ihe desIinaIion IiIe is overwriIIen beIore iI can be copied Io a
posiIion IaIer in Ihe IiIe. This does noI appIy iI you use --backup, since rsync
is smarI enough Io use Ihe backup IiIe as Ihe basis IiIe Ior Ihe IransIer.
WARN!NC: you shouId noI use Ihis opIion Io updaIe IiIes IhaI are being accessed by
oIhers, so be careIuI when choosing Io use Ihis Ior a copy.
This opIion is useIuI Ior IransIerring Iarge IiIes wiIh bIock-based changes or appended
daIa, and aIso on sysIems IhaI are disk bound, noI neIwork bound. !I can aIso heIp
keep a copy-on-wriIe IiIesysIem snapshoI Irom diverging Ihe enIire conIenIs oI a IiIe
IhaI onIy has minor changes.
The opIion impIies --partial (since an inIerrupIed IransIer does noI deIeIe Ihe IiIe), buI
conIIicIs wiIh --partial-dir and --delay-updates. Prior Io rsync 2.6.4 --inplace was aIso
incompaIibIe wiIh --compare-dest and --link-dest.
--append
This causes rsync Io updaIe a IiIe by appending daIa onIo Ihe end oI Ihe IiIe, which
presumes IhaI Ihe daIa IhaI aIready exisIs on Ihe receiving side is idenIicaI wiIh Ihe
sIarI oI Ihe IiIe on Ihe sending side. !I a IiIe needs Io be IransIerred and iIs size on Ihe
receiver is Ihe same or Ionger Ihan Ihe size on Ihe sender, Ihe IiIe is skipped. This does
noI inIerIere wiIh Ihe updaIing oI a IiIe's non-conIenI aIIribuIes (e.g. permissions,
ownership, eIc.) when Ihe IiIe does noI need Io be IransIerred, nor does iI aIIecI Ihe
updaIing oI any non-reguIar IiIes. !mpIies --inplace, buI does noI conIIicI wiIh --sparse
(since iI is aIways exIending a IiIe's IengIh).
--append-verify
This works |usI Iike Ihe --append opIion, buI Ihe exisIing daIa on Ihe receiving side is
incIuded in Ihe IuII-IiIe checksum veriIicaIion sIep, which wiII cause a IiIe Io be resenI
iI Ihe IinaI veriIicaIion sIep IaiIs (rsync uses a normaI, non-appending --inplace
IransIer Ior Ihe resend).
NoIe: prior Io rsync 3.0.0, Ihe --append opIion worked Iike --append-verify, so iI you
are inIeracIing wiIh an oIder rsync (or Ihe IransIer is using a proIocoI prior Io 30),
speciIying eiIher append opIion wiII iniIiaIe an --append-verify IransIer.
-d, --dirs
TeII Ihe sending side Io incIude any direcIories IhaI are encounIered. UnIike
--recursive, a direcIory's conIenIs are noI copied unIess Ihe direcIory name speciIied is
"." or ends wiIh a IraiIing sIash (e.g. ".", "dir/.", "dir/", eIc.). WiIhouI Ihis opIion or Ihe
--recursive opIion, rsync wiII skip aII direcIories iI encounIers (and ouIpuI a message
Io IhaI eIIecI Ior each one). !I you speciIy boIh --dirs and --recursive, --recursive Iakes
precedence.
The --dirs opIion is impIied by Ihe --files-from opIion or Ihe --list-only opIion
(incIuding an impIied --list-only usage) iI --recursive wasn'I speciIied (so IhaI
direcIories are seen in Ihe IisIing). SpeciIy --no-dirs (or --no-d) iI you wanI Io Iurn Ihis
oII.
There is aIso a backward-compaIibiIiIy heIper opIion, --old-dirs (or --old-d) IhaI IeIIs
rsync Io use a hack oI "-r --excIude='/"/"'" Io geI an oIder rsync Io IisI a singIe direcIory
wiIhouI recursing.
-l, --links
When symIinks are encounIered, recreaIe Ihe symIink on Ihe desIinaIion.
-L, --copy-links
When symIinks are encounIered, Ihe iIem IhaI Ihey poinI Io (Ihe reIerenI) is copied,
1S sur SS 23/03/2013 17:4S
raIher Ihan Ihe symIink. !n oIder versions oI rsync, Ihis opIion aIso had Ihe side-eIIecI
oI IeIIing Ihe receiving side Io IoIIow symIinks, such as symIinks Io direcIories. !n a
modern rsync such as Ihis one, you'II need Io speciIy --keep-dirlinks (-K) Io geI Ihis
exIra behavior. The onIy excepIion is when sending IiIes Io an rsync IhaI is Ioo oId Io
undersIand -K -- in IhaI case, Ihe -L opIion wiII sIiII have Ihe side-eIIecI oI -K on IhaI
oIder receiving rsync.
--copy-unsafe-links
This IeIIs rsync Io copy Ihe reIerenI oI symboIic Iinks IhaI poinI ouIside Ihe copied Iree.
AbsoIuIe symIinks are aIso IreaIed Iike ordinary IiIes, and so are any symIinks in Ihe
source paIh iIseII when --relative is used. This opIion has no addiIionaI eIIecI iI
--copy-links was aIso speciIied.
--safe-links
This IeIIs rsync Io ignore any symboIic Iinks which poinI ouIside Ihe copied Iree. AII
absoIuIe symIinks are aIso ignored. Using Ihis opIion in con|uncIion wiIh --relative
may give unexpecIed resuIIs.
-k, --copy-dirlinks
This opIion causes Ihe sending side Io IreaI a symIink Io a direcIory as Ihough iI were a
reaI direcIory. This is useIuI iI you don'I wanI symIinks Io non-direcIories Io be
aIIecIed, as Ihey wouId be using --copy-links.
WiIhouI Ihis opIion, iI Ihe sending side has repIaced a direcIory wiIh a symIink Io a
direcIory, Ihe receiving side wiII deIeIe anyIhing IhaI is in Ihe way oI Ihe new symIink,
incIuding a direcIory hierarchy (as Iong as --force or --delete is in eIIecI).
See aIso --keep-dirlinks Ior an anaIogous opIion Ior Ihe receiving side.
--copy-dirlinks appIies Io aII symIinks Io direcIories in Ihe source. !I you wanI Io
IoIIow onIy a Iew speciIied symIinks, a Irick you can use is Io pass Ihem as addiIionaI
source args wiIh a IraiIing sIash, using --relative Io make Ihe paIhs maIch up righI. or
exampIe:
rsync -r --relal1ve src1.1 src1.1iolloW-me1 desl1
This works because rsync caIIs lstat(2) on Ihe source arg as given, and Ihe IraiIing
sIash makes lstat(2) IoIIow Ihe symIink, giving rise Io a direcIory in Ihe IiIe-IisI which
overrides Ihe symIink Iound during Ihe scan oI "src/./".
-K, --keep-dirlinks
This opIion causes Ihe receiving side Io IreaI a symIink Io a direcIory as Ihough iI were
a reaI direcIory, buI onIy iI iI maIches a reaI direcIory Irom Ihe sender. WiIhouI Ihis
opIion, Ihe receiver's symIink wouId be deIeIed and repIaced wiIh a reaI direcIory.
or exampIe, suppose you IransIer a direcIory "Ioo" IhaI conIains a IiIe "IiIe", buI "Ioo"
is a symIink Io direcIory "bar" on Ihe receiver. WiIhouI --keep-dirlinks, Ihe receiver
deIeIes symIink "Ioo", recreaIes iI as a direcIory, and receives Ihe IiIe inIo Ihe new
direcIory. WiIh --keep-dirlinks, Ihe receiver keeps Ihe symIink and "IiIe" ends up in
"bar".
One noIe oI cauIion: iI you use --keep-dirlinks, you musI IrusI aII Ihe symIinks in Ihe
copy! !I iI is possibIe Ior an unIrusIed user Io creaIe Iheir own symIink Io any direcIory,
Ihe user couId Ihen (on a subseguenI copy) repIace Ihe symIink wiIh a reaI direcIory
and aIIecI Ihe conIenI oI whaIever direcIory Ihe symIink reIerences. or backup
copies, you are beIIer oII using someIhing Iike a bind mounI insIead oI a symIink Io
modiIy your receiving hierarchy.
See aIso --copy-dirlinks Ior an anaIogous opIion Ior Ihe sending side.
16 sur SS 23/03/2013 17:4S
-H, --hard-links
This IeIIs rsync Io Iook Ior hard-Iinked IiIes in Ihe source and Iink IogeIher Ihe
corresponding IiIes on Ihe desIinaIion. WiIhouI Ihis opIion, hard-Iinked IiIes in Ihe
source are IreaIed as Ihough Ihey were separaIe IiIes.
This opIion does NOT necessariIy ensure IhaI Ihe paIIern oI hard Iinks on Ihe
desIinaIion exacIIy maIches IhaI on Ihe source. Cases in which Ihe desIinaIion may end
up wiIh exIra hard Iinks incIude Ihe IoIIowing:
o
!I Ihe desIinaIion conIains exIraneous hard-Iinks (more Iinking Ihan whaI is
presenI in Ihe source IiIe IisI), Ihe copying aIgoriIhm wiII noI break Ihem
expIiciIIy. However, iI one or more oI Ihe paIhs have conIenI diIIerences, Ihe
normaI IiIe-updaIe process wiII break Ihose exIra Iinks (unIess you are using
Ihe --inplace opIion).
o
!I you speciIy a --link-dest direcIory IhaI conIains hard Iinks, Ihe Iinking oI
Ihe desIinaIion IiIes againsI Ihe --link-dest IiIes can cause some paIhs in Ihe
desIinaIion Io become Iinked IogeIher due Io Ihe --link-dest associaIions.
NoIe IhaI rsync can onIy deIecI hard Iinks beIween IiIes IhaI are inside Ihe IransIer seI.
!I rsync updaIes a IiIe IhaI has exIra hard-Iink connecIions Io IiIes ouIside Ihe IransIer,
IhaI Iinkage wiII be broken. !I you are IempIed Io use Ihe --inplace opIion Io avoid Ihis
breakage, be very careIuI IhaI you know how your IiIes are being updaIed so IhaI you
are cerIain IhaI no uninIended changes happen due Io Iingering hard Iinks (and see
Ihe --inplace opIion Ior more caveaIs).
!I incremenIaI recursion is acIive (see --recursive), rsync may IransIer a missing
hard-Iinked IiIe beIore iI Iinds IhaI anoIher Iink Ior IhaI conIenIs exisIs eIsewhere in
Ihe hierarchy. This does noI aIIecI Ihe accuracy oI Ihe IransIer (i.e. which IiIes are
hard-Iinked IogeIher), |usI iIs eIIiciency (i.e. copying Ihe daIa Ior a new, earIy copy oI a
hard-Iinked IiIe IhaI couId have been Iound IaIer in Ihe IransIer in anoIher member oI
Ihe hard-Iinked seI oI IiIes). One way Io avoid Ihis ineIIiciency is Io disabIe incremenIaI
recursion using Ihe --no-inc-recursive opIion.
-p, --perms
This opIion causes Ihe receiving rsync Io seI Ihe desIinaIion permissions Io be Ihe same
as Ihe source permissions. (See aIso Ihe --chmod opIion Ior a way Io modiIy whaI rsync
considers Io be Ihe source permissions.)
When Ihis opIion is ojj, permissions are seI as IoIIows:
o
xisIing IiIes (incIuding updaIed IiIes) reIain Iheir exisIing permissions,
Ihough Ihe --executability opIion mighI change |usI Ihe execuIe permission
Ior Ihe IiIe.
o
New IiIes geI Iheir "normaI" permission biIs seI Io Ihe source IiIe's
permissions masked wiIh Ihe receiving direcIory's deIauII permissions
(eiIher Ihe receiving process's umask, or Ihe permissions speciIied via Ihe
desIinaIion direcIory's deIauII ACL), and Iheir speciaI permission biIs
disabIed excepI in Ihe case where a new direcIory inheriIs a seIgid biI Irom
iIs parenI direcIory.
17 sur SS 23/03/2013 17:4S
Thus, when --perms and --executability are boIh disabIed, rsync's behavior is Ihe
same as IhaI oI oIher IiIe-copy uIiIiIies, such as cp(1) and tar(1).
!n summary: Io give desIinaIion IiIes (boIh oId and new) Ihe source permissions, use
--perms. To give new IiIes Ihe desIinaIion-deIauII permissions (whiIe Ieaving exisIing
IiIes unchanged), make sure IhaI Ihe --perms opIion is oII and use --chmod=ugo=rwX
(which ensures IhaI aII non-masked biIs geI enabIed). !I you'd care Io make Ihis IaIIer
behavior easier Io Iype, you couId deIine a popI aIias Ior iI, such as puIIing Ihis Iine in
Ihe IiIe ~/.popI (Ihe IoIIowing deIines Ihe -Z opIion, and incIudes --no-g Io use Ihe
deIauII group oI Ihe desIinaIion dir):
rsync al1as -Z --no-p --no- --chmod=uo=rWX
You couId Ihen use Ihis new opIion in a command such as Ihis one:
rsync -avZ src1 desl1
(CaveaI: make sure IhaI -a does noI IoIIow -Z, or iI wiII re-enabIe Ihe Iwo "--no-""
opIions menIioned above.)
The preservaIion oI Ihe desIinaIion's seIgid biI on newIy-creaIed direcIories when
--perms is oII was added in rsync 2.6.7. OIder rsync versions erroneousIy preserved
Ihe Ihree speciaI permission biIs Ior newIy-creaIed IiIes when --perms was oII, whiIe
overriding Ihe desIinaIion's seIgid biI seIIing on a newIy-creaIed direcIory. DeIauII ACL
observance was added Io Ihe ACL paIch Ior rsync 2.6.7, so oIder (or non-ACL-enabIed)
rsyncs use Ihe umask even iI deIauII ACLs are presenI. (Keep in mind IhaI iI is Ihe
version oI Ihe receiving rsync IhaI aIIecIs Ihese behaviors.)
-L, --executability
This opIion causes rsync Io preserve Ihe execuIabiIiIy (or non-execuIabiIiIy) oI reguIar
IiIes when --perms is noI enabIed. A reguIar IiIe is considered Io be execuIabIe iI aI
IeasI one 'x' is Iurned on in iIs permissions. When an exisIing desIinaIion IiIe's
execuIabiIiIy diIIers Irom IhaI oI Ihe corresponding source IiIe, rsync modiIies Ihe
desIinaIion IiIe's permissions as IoIIows:
o
To make a IiIe non-execuIabIe, rsync Iurns oII aII iIs 'x' permissions.
o
To make a IiIe execuIabIe, rsync Iurns on each 'x' permission IhaI has a
corresponding 'r' permission enabIed.
!I --perms is enabIed, Ihis opIion is ignored.
-A, --acls
This opIion causes rsync Io updaIe Ihe desIinaIion ACLs Io be Ihe same as Ihe source
ACLs. The opIion aIso impIies --perms.
The source and desIinaIion sysIems musI have compaIibIe ACL enIries Ior Ihis opIion
Io work properIy. See Ihe --fake-super opIion Ior a way Io backup and resIore ACLs
IhaI are noI compaIibIe.
-X, --xattrs
This opIion causes rsync Io updaIe Ihe desIinaIion exIended aIIribuIes Io be Ihe same
as Ihe source ones.
or sysIems IhaI supporI exIended-aIIribuIe namespaces, a copy being done by a
super-user copies aII namespaces excepI sysIem.". A normaI user onIy copies Ihe user."
namespace. To be abIe Io backup and resIore non-user namespaces as a normaI user,
18 sur SS 23/03/2013 17:4S
see Ihe --fake-super opIion.
NoIe IhaI Ihis opIion does noI copy rsyncs speciaI xaIIr vaIues (e.g. Ihose used by
--fake-super) unIess you repeaI Ihe opIion (e.g. -XX). This "copy aII xaIIrs" mode cannoI
be used wiIh --fake-super.
--chmod
This opIion IeIIs rsync Io appIy one or more comma-separaIed "chmod" modes Io Ihe
permission oI Ihe IiIes in Ihe IransIer. The resuIIing vaIue is IreaIed as Ihough iI were
Ihe permissions IhaI Ihe sending side suppIied Ior Ihe IiIe, which means IhaI Ihis
opIion can seem Io have no eIIecI on exisIing IiIes iI --perms is noI enabIed.
!n addiIion Io Ihe normaI parsing ruIes speciIied in Ihe chmod(1) manpage, you can
speciIy an iIem IhaI shouId onIy appIy Io a direcIory by preIixing iI wiIh a 'D', or
speciIy an iIem IhaI shouId onIy appIy Io a IiIe by preIixing iI wiIh a ''. or exampIe,
Ihe IoIIowing wiII ensure IhaI aII direcIories geI marked seI-gid, IhaI no IiIes are oIher-
wriIabIe, IhaI boIh are user-wriIabIe and group-wriIabIe, and IhaI boIh have consisIenI
execuIabiIiIy across aII biIs:
--chmod=Dgs,ugw,o-w,X
!I is aIso IegaI Io speciIy muIIipIe --chmod opIions, as each addiIionaI opIion is |usI
appended Io Ihe IisI oI changes Io make.
See Ihe --perms and --executability opIions Ior how Ihe resuIIing permission vaIue
can be appIied Io Ihe IiIes in Ihe IransIer.
-o, --owner
This opIion causes rsync Io seI Ihe owner oI Ihe desIinaIion IiIe Io be Ihe same as Ihe
source IiIe, buI onIy iI Ihe receiving rsync is being run as Ihe super-user (see aIso Ihe
--super and --fake-super opIions). WiIhouI Ihis opIion, Ihe owner oI new and/or
IransIerred IiIes are seI Io Ihe invoking user on Ihe receiving side.
The preservaIion oI ownership wiII associaIe maIching names by deIauII, buI may IaII
back Io using Ihe !D number in some circumsIances (see aIso Ihe --numeric-ids opIion
Ior a IuII discussion).
-g, --group
This opIion causes rsync Io seI Ihe group oI Ihe desIinaIion IiIe Io be Ihe same as Ihe
source IiIe. !I Ihe receiving program is noI running as Ihe super-user (or iI --no-super
was speciIied), onIy groups IhaI Ihe invoking user on Ihe receiving side is a member oI
wiII be preserved. WiIhouI Ihis opIion, Ihe group is seI Io Ihe deIauII group oI Ihe
invoking user on Ihe receiving side.
The preservaIion oI group inIormaIion wiII associaIe maIching names by deIauII, buI
may IaII back Io using Ihe !D number in some circumsIances (see aIso Ihe
--numeric-ids opIion Ior a IuII discussion).
--devices
This opIion causes rsync Io IransIer characIer and bIock device IiIes Io Ihe remoIe
sysIem Io recreaIe Ihese devices. This opIion has no eIIecI iI Ihe receiving rsync is noI
run as Ihe super-user (see aIso Ihe --super and --fake-super opIions).
--specials
This opIion causes rsync Io IransIer speciaI IiIes such as named sockeIs and IiIos.
-D
The -D opIion is eguivaIenI Io --devices --specials.
-t, --times
This IeIIs rsync Io IransIer modiIicaIion Iimes aIong wiIh Ihe IiIes and updaIe Ihem on
19 sur SS 23/03/2013 17:4S
Ihe remoIe sysIem. NoIe IhaI iI Ihis opIion is noI used, Ihe opIimizaIion IhaI excIudes
IiIes IhaI have noI been modiIied cannoI be eIIecIive; in oIher words, a missing -t or -a
wiII cause Ihe nexI IransIer Io behave as iI iI used -I, causing aII IiIes Io be updaIed
(Ihough rsync's deIIa-IransIer aIgoriIhm wiII make Ihe updaIe IairIy eIIicienI iI Ihe IiIes
haven'I acIuaIIy changed, you're much beIIer oII using -t).
-O, --omit-dir-times
This IeIIs rsync Io omiI direcIories when iI is preserving modiIicaIion Iimes (see
--times). !I NS is sharing Ihe direcIories on Ihe receiving side, iI is a good idea Io use
-O. This opIion is inIerred iI you use --backup wiIhouI --backup-dir.
--super
This IeIIs Ihe receiving side Io aIIempI super-user acIiviIies even iI Ihe receiving rsync
wasn'I run by Ihe super-user. These acIiviIies incIude: preserving users via Ihe --owner
opIion, preserving aII groups (noI |usI Ihe currenI user's groups) via Ihe --groups
opIion, and copying devices via Ihe --devices opIion. This is useIuI Ior sysIems IhaI
aIIow such acIiviIies wiIhouI being Ihe super-user, and aIso Ior ensuring IhaI you wiII
geI errors iI Ihe receiving side isn'I being run as Ihe super-user. To Iurn oII super-user
acIiviIies, Ihe super-user can use --no-super.
--fake-super
When Ihis opIion is enabIed, rsync simuIaIes super-user acIiviIies by saving/resIoring
Ihe priviIeged aIIribuIes via speciaI exIended aIIribuIes IhaI are aIIached Io each IiIe
(as needed). This incIudes Ihe IiIe's owner and group (iI iI is noI Ihe deIauII), Ihe IiIe's
device inIo (device & speciaI IiIes are creaIed as empIy IexI IiIes), and any permission
biIs IhaI we won'I aIIow Io be seI on Ihe reaI IiIe (e.g. Ihe reaI IiIe geIs u-s,g-s,o-I Ior
saIeIy) or IhaI wouId IimiI Ihe owner's access (since Ihe reaI super-user can aIways
access/change a IiIe, Ihe IiIes we creaIe can aIways be accessed/changed by Ihe creaIing
user). This opIion aIso handIes ACLs (iI --acls was speciIied) and non-user exIended
aIIribuIes (iI --xattrs was speciIied).
This is a good way Io backup daIa wiIhouI using a super-user, and Io sIore ACLs Irom
incompaIibIe sysIems.
The --fake-super opIion onIy aIIecIs Ihe side where Ihe opIion is used. To aIIecI Ihe
remoIe side oI a remoIe-sheII connecIion, speciIy an rsync paIh:
rsync -av --rsync-palh="rsync --iake-super" 1src1 hosl.1desl1
Since Ihere is onIy one "side" in a IocaI copy, Ihis opIion aIIecIs boIh Ihe sending and
receiving oI IiIes. You'II need Io speciIy a copy using "IocaIhosI" iI you need Io avoid
Ihis, possibIy using Ihe "Ish" sheII scripI (Irom Ihe supporI direcIory) as a subsIiIuIe Ior
an acIuaI remoIe sheII (see --rsh).
This opIion is overridden by boIh --super and --no-super.
See aIso Ihe "Iake super" seIIing in Ihe daemon's rsyncd.conI IiIe.
-S, --sparse
Try Io handIe sparse IiIes eIIicienIIy so Ihey Iake up Iess space on Ihe desIinaIion.
ConIIicIs wiIh --inplace because iI's noI possibIe Io overwriIe daIa in a sparse Iashion.
-n, --dry-run
This makes rsync perIorm a IriaI run IhaI doesn'I make any changes (and produces
mosIIy Ihe same ouIpuI as a reaI run). !I is mosI commonIy used in combinaIion wiIh
Ihe -v, --verbose and/or -i, --itemize-changes opIions Io see whaI an rsync command is
going Io do beIore one acIuaIIy runs iI.
The ouIpuI oI --itemize-changes is supposed Io be exacIIy Ihe same on a dry run and a
20 sur SS 23/03/2013 17:4S
subseguenI reaI run (barring inIenIionaI Irickery and sysIem caII IaiIures); iI iI isn'I,
IhaI's a bug. OIher ouIpuI shouId be mosIIy unchanged, buI may diIIer in some areas.
NoIabIy, a dry run does noI send Ihe acIuaI daIa Ior IiIe IransIers, so --progress has no
eIIecI, Ihe "byIes senI", "byIes received", "IiIeraI daIa", and "maIched daIa" sIaIisIics are
Ioo smaII, and Ihe "speedup" vaIue is eguivaIenI Io a run where no IiIe IransIers were
needed.
-W, --whole-file
WiIh Ihis opIion rsync's deIIa-IransIer aIgoriIhm is noI used and Ihe whoIe IiIe is senI
as-is insIead. The IransIer may be IasIer iI Ihis opIion is used when Ihe bandwidIh
beIween Ihe source and desIinaIion machines is higher Ihan Ihe bandwidIh Io disk
(especiaIIy when Ihe "disk" is acIuaIIy a neIworked IiIesysIem). This is Ihe deIauII
when boIh Ihe source and desIinaIion are speciIied as IocaI paIhs, buI onIy iI no baIch-
wriIing opIion is in eIIecI.
-x, --one-file-system
This IeIIs rsync Io avoid crossing a IiIesysIem boundary when recursing. This does noI
IimiI Ihe user's abiIiIy Io speciIy iIems Io copy Irom muIIipIe IiIesysIems, |usI rsync's
recursion Ihrough Ihe hierarchy oI each direcIory IhaI Ihe user speciIied, and aIso Ihe
anaIogous recursion on Ihe receiving side during deIeIion. AIso keep in mind IhaI
rsync IreaIs a "bind" mounI Io Ihe same device as being on Ihe same IiIesysIem.
!I Ihis opIion is repeaIed, rsync omiIs aII mounI-poinI direcIories Irom Ihe copy.
OIherwise, iI incIudes an empIy direcIory aI each mounI-poinI iI encounIers (using Ihe
aIIribuIes oI Ihe mounIed direcIory because Ihose oI Ihe underIying mounI-poinI
direcIory are inaccessibIe).
!I rsync has been IoId Io coIIapse symIinks (via --copy-links or --copy-unsafe-links), a
symIink Io a direcIory on anoIher device is IreaIed Iike a mounI-poinI. SymIinks Io
non-direcIories are unaIIecIed by Ihis opIion.
--existing, --ignore-non-existing
This IeIIs rsync Io skip creaIing IiIes (incIuding direcIories) IhaI do noI exisI yeI on Ihe
desIinaIion. !I Ihis opIion is combined wiIh Ihe --ignore-existing opIion, no IiIes wiII
be updaIed (which can be useIuI iI aII you wanI Io do is deIeIe exIraneous IiIes).
--ignore-existing
This IeIIs rsync Io skip updaIing IiIes IhaI aIready exisI on Ihe desIinaIion (Ihis does not
ignore exisIing direcIories, or noIhing wouId geI done). See aIso --existing.
This opIion can be useIuI Ior Ihose doing backups using Ihe --link-dest opIion when
Ihey need Io conIinue a backup run IhaI goI inIerrupIed. Since a --link-dest run is
copied inIo a new direcIory hierarchy (when iI is used properIy), using --ignore
existing wiII ensure IhaI Ihe aIready-handIed IiIes don'I geI Iweaked (which avoids a
change in permissions on Ihe hard-Iinked IiIes). This does mean IhaI Ihis opIion is onIy
Iooking aI Ihe exisIing IiIes in Ihe desIinaIion hierarchy iIseII.
--remove-source-files
This IeIIs rsync Io remove Irom Ihe sending side Ihe IiIes (meaning non-direcIories)
IhaI are a parI oI Ihe IransIer and have been successIuIIy dupIicaIed on Ihe receiving
21 sur SS 23/03/2013 17:4S
side.
NoIe IhaI you shouId onIy use Ihis opIion on source IiIes IhaI are guiescenI. !I you are
using Ihis Io move IiIes IhaI show up in a parIicuIar direcIory over Io anoIher hosI,
make sure IhaI Ihe Iinished IiIes geI renamed inIo Ihe source direcIory, noI direcIIy
wriIIen inIo iI, so IhaI rsync can'I possibIy IransIer a IiIe IhaI is noI yeI IuIIy wriIIen. !I
you can'I IirsI wriIe Ihe IiIes inIo a diIIerenI direcIory, you shouId use a naming idiom
IhaI IeIs rsync avoid IransIerring IiIes IhaI are noI yeI Iinished (e.g. name Ihe IiIe
"Ioo.new" when iI is wriIIen, rename iI Io "Ioo" when iI is done, and Ihen use Ihe
opIion --exclude='*.new' Ior Ihe rsync IransIer).
--delete
This IeIIs rsync Io deIeIe exIraneous IiIes Irom Ihe receiving side (ones IhaI aren'I on
Ihe sending side), buI onIy Ior Ihe direcIories IhaI are being synchronized. You musI
have asked rsync Io send Ihe whoIe direcIory (e.g. "dir" or "dir/") wiIhouI using a
wiIdcard Ior Ihe direcIory's conIenIs (e.g. "dir/"") since Ihe wiIdcard is expanded by Ihe
sheII and rsync Ihus geIs a reguesI Io IransIer individuaI IiIes, noI Ihe IiIes' parenI
direcIory. iIes IhaI are excIuded Irom Ihe IransIer are aIso excIuded Irom being
deIeIed unIess you use Ihe --delete-excluded opIion or mark Ihe ruIes as onIy
maIching on Ihe sending side (see Ihe incIude/excIude modiIiers in Ihe !LTR RULS
secIion).
Prior Io rsync 2.6.7, Ihis opIion wouId have no eIIecI unIess --recursive was enabIed.
8eginning wiIh 2.6.7, deIeIions wiII aIso occur when --dirs (-d) is enabIed, buI onIy Ior
direcIories whose conIenIs are being copied.
This opIion can be dangerous iI used incorrecIIy! !I is a very good idea Io IirsI Iry a run
using Ihe --dry-run opIion (-n) Io see whaI IiIes are going Io be deIeIed.
!I Ihe sending side deIecIs any !/O errors, Ihen Ihe deIeIion oI any IiIes aI Ihe
desIinaIion wiII be auIomaIicaIIy disabIed. This is Io prevenI Iemporary IiIesysIem
IaiIures (such as NS errors) on Ihe sending side Irom causing a massive deIeIion oI
IiIes on Ihe desIinaIion. You can override Ihis wiIh Ihe --ignore-errors opIion.
The --delete opIion may be combined wiIh one oI Ihe --deIeIe-WHN opIions wiIhouI
conIIicI, as weII as --delete-excluded. However, iI none oI Ihe --deIeIe-WHN opIions
are speciIied, rsync wiII choose Ihe --delete-during aIgoriIhm when IaIking Io rsync
3.0.0 or newer, and Ihe --delete-before aIgoriIhm when IaIking Io an oIder rsync. See
aIso --delete-delay and --delete-after.
--delete-before
ReguesI IhaI Ihe IiIe-deIeIions on Ihe receiving side be done beIore Ihe IransIer sIarIs.
See --delete (which is impIied) Ior more deIaiIs on IiIe-deIeIion.
DeIeIing beIore Ihe IransIer is heIpIuI iI Ihe IiIesysIem is IighI Ior space and removing
exIraneous IiIes wouId heIp Io make Ihe IransIer possibIe. However, iI does inIroduce a
deIay beIore Ihe sIarI oI Ihe IransIer, and Ihis deIay mighI cause Ihe IransIer Io IimeouI
(iI --timeout was speciIied). !I aIso Iorces rsync Io use Ihe oId, non-incremenIaI
recursion aIgoriIhm IhaI reguires rsync Io scan aII Ihe IiIes in Ihe IransIer inIo
memory aI once (see --recursive).
--delete-during, --del
ReguesI IhaI Ihe IiIe-deIeIions on Ihe receiving side be done incremenIaIIy as Ihe
IransIer happens. The per-direcIory deIeIe scan is done righI beIore each direcIory is
checked Ior updaIes, so iI behaves Iike a more eIIicienI --delete-before, incIuding
doing Ihe deIeIions prior Io any per-direcIory IiIIer IiIes being updaIed. This opIion
was IirsI added in rsync version 2.6.4. See --delete (which is impIied) Ior more deIaiIs
22 sur SS 23/03/2013 17:4S
on IiIe-deIeIion.
--delete-delay
ReguesI IhaI Ihe IiIe-deIeIions on Ihe receiving side be compuIed during Ihe IransIer
(Iike --delete-during), and Ihen removed aIIer Ihe IransIer compIeIes. This is useIuI
when combined wiIh --delay-updates and/or --fuzzy, and is more eIIicienI Ihan using
--delete-after (buI can behave diIIerenIIy, since --delete-after compuIes Ihe deIeIions
in a separaIe pass aIIer aII updaIes are done). !I Ihe number oI removed IiIes overIIows
an inIernaI buIIer, a Iemporary IiIe wiII be creaIed on Ihe receiving side Io hoId Ihe
names (iI is removed whiIe open, so you shouIdn'I see iI during Ihe IransIer). !I Ihe
creaIion oI Ihe Iemporary IiIe IaiIs, rsync wiII Iry Io IaII back Io using --delete-after
(which iI cannoI do iI --recursive is doing an incremenIaI scan). See --delete (which is
impIied) Ior more deIaiIs on IiIe-deIeIion.
--delete-after
ReguesI IhaI Ihe IiIe-deIeIions on Ihe receiving side be done aIIer Ihe IransIer has
compIeIed. This is useIuI iI you are sending new per-direcIory merge IiIes as a parI oI
Ihe IransIer and you wanI Iheir excIusions Io Iake eIIecI Ior Ihe deIeIe phase oI Ihe
currenI IransIer. !I aIso Iorces rsync Io use Ihe oId, non-incremenIaI recursion
aIgoriIhm IhaI reguires rsync Io scan aII Ihe IiIes in Ihe IransIer inIo memory aI once
(see --recursive). See --delete (which is impIied) Ior more deIaiIs on IiIe-deIeIion.
--delete-excluded
!n addiIion Io deIeIing Ihe IiIes on Ihe receiving side IhaI are noI on Ihe sending side,
Ihis IeIIs rsync Io aIso deIeIe any IiIes on Ihe receiving side IhaI are excIuded (see
--exclude). See Ihe !LTR RULS secIion Ior a way Io make individuaI excIusions
behave Ihis way on Ihe receiver, and Ior a way Io proIecI IiIes Irom --delete-excluded.
See --delete (which is impIied) Ior more deIaiIs on IiIe-deIeIion.
--ignore-errors
TeIIs --delete Io go ahead and deIeIe IiIes even when Ihere are !/O errors.
--force
This opIion IeIIs rsync Io deIeIe a non-empIy direcIory when iI is Io be repIaced by a
non-direcIory. This is onIy reIevanI iI deIeIions are noI acIive (see --delete Ior deIaiIs).
NoIe Ior oIder rsync versions: --force used Io sIiII be reguired when using --delete-
after, and iI used Io be non-IuncIionaI unIess Ihe --recursive opIion was aIso enabIed.
--max-delete=NUM
This IeIIs rsync noI Io deIeIe more Ihan NUM IiIes or direcIories. !I IhaI IimiI is
exceeded, a warning is ouIpuI and rsync exiIs wiIh an error code oI 2S (new Ior 3.0.0).
AIso new Ior version 3.0.0, you may speciIy --max-delete=0 Io be warned abouI any
exIraneous IiIes in Ihe desIinaIion wiIhouI removing any oI Ihem. OIder cIienIs
inIerpreIed Ihis as "unIimiIed", so iI you don'I know whaI version Ihe cIienI is, you can
use Ihe Iess obvious --max-delete=-1 as a backward-compaIibIe way Io speciIy IhaI no
deIeIions be aIIowed (Ihough oIder versions didn'I warn when Ihe IimiI was exceeded).
--max-size=SIZL
This IeIIs rsync Io avoid IransIerring any IiIe IhaI is Iarger Ihan Ihe speciIied S!Z. The
S!Z vaIue can be suIIixed wiIh a sIring Io indicaIe a size muIIipIier, and may be a
IracIionaI vaIue (e.g. "--max-size=1.5m").
The suIIixes are as IoIIows: "K" (or "Ki8") is a kibibyIe (1024), "M" (or "Mi8") is a
23 sur SS 23/03/2013 17:4S
mebibyIe (1024"1024), and "C" (or "Ci8") is a gibibyIe (1024"1024"1024). !I you wanI
Ihe muIIipIier Io be 1000 insIead oI 1024, use "K8", "M8", or "C8". (NoIe: Iower-case is
aIso accepIed Ior aII vaIues.) inaIIy, iI Ihe suIIix ends in eiIher "1" or "-1", Ihe vaIue
wiII be oIIseI by one byIe in Ihe indicaIed direcIion.
xampIes: --max-size=1.Smb-1 is 1499999 byIes, and --max-size=2g1 is 2147483649
byIes.
--min-size=SIZL
This IeIIs rsync Io avoid IransIerring any IiIe IhaI is smaIIer Ihan Ihe speciIied S!Z,
which can heIp in noI IransIerring smaII, |unk IiIes. See Ihe --max-size opIion Ior a
descripIion oI S!Z and oIher inIormaIion.
-B, --block-size=BLOCKSIZL
This Iorces Ihe bIock size used in rsync's deIIa-IransIer aIgoriIhm Io a Iixed vaIue. !I is
normaIIy seIecIed based on Ihe size oI each IiIe being updaIed. See Ihe IechnicaI reporI
Ior deIaiIs.
-e, --rsh=COMMAND
This opIion aIIows you Io choose an aIIernaIive remoIe sheII program Io use Ior
communicaIion beIween Ihe IocaI and remoIe copies oI rsync. TypicaIIy, rsync is
conIigured Io use ssh by deIauII, buI you may preIer Io use rsh on a IocaI neIwork.
!I Ihis opIion is used wiIh juser@|host::modulejpath, Ihen Ihe remoIe sheII
CDMMAND wiII be used Io run an rsync daemon on Ihe remoIe hosI, and aII daIa wiII
be IransmiIIed Ihrough IhaI remoIe sheII connecIion, raIher Ihan Ihrough a direcI
sockeI connecIion Io a running rsync daemon on Ihe remoIe hosI. See Ihe secIion
"US!NC RSYNC-DAMON ATURS V!A A RMOT-SHLL CONNCT!ON" above.
Command-Iine argumenIs are permiIIed in COMMAND provided IhaI COMMAND is
presenIed Io rsync as a singIe argumenI. You musI use spaces (noI Iabs or oIher
whiIespace) Io separaIe Ihe command and args Irom each oIher, and you can use
singIe- and/or doubIe-guoIes Io preserve spaces in an argumenI (buI noI backsIashes).
NoIe IhaI doubIing a singIe-guoIe inside a singIe-guoIed sIring gives you a singIe-guoIe;
Iikewise Ior doubIe-guoIes (Ihough you need Io pay aIIenIion Io which guoIes your
sheII is parsing and which guoIes rsync is parsing). Some exampIes:
-e `ssh -p 2234`
-e `ssh -o "ProxyCommand nohup ssh i1reWall nc -W1 7h 7p"`
(NoIe IhaI ssh users can aIIernaIeIy cusIomize siIe-speciIic connecI opIions in Iheir
.ssh/conIig IiIe.)
You can aIso choose Ihe remoIe sheII program using Ihe RSYNC_RSH environmenI
variabIe, which accepIs Ihe same range oI vaIues as -e.
See aIso Ihe --blocking-io opIion which is aIIecIed by Ihis opIion.
--rsync-path=PROGRAM
Use Ihis Io speciIy whaI program is Io be run on Ihe remoIe machine Io sIarI-up rsync.
OIIen used when rsync is noI in Ihe deIauII remoIe-sheII's paIh (e.g. --rsync-paIh=/usr
/IocaI/bin/rsync). NoIe IhaI PROCRAM is run wiIh Ihe heIp oI a sheII, so iI can be any
program, scripI, or command seguence you'd care Io run, so Iong as iI does noI corrupI
Ihe sIandard-in & sIandard-ouI IhaI rsync is using Io communicaIe.
One Iricky exampIe is Io seI a diIIerenI deIauII direcIory on Ihe remoIe machine Ior
use wiIh Ihe --relative opIion. or insIance:
rsync -avR --rsync-palh="cd 1a1b && rsync" hosl.c1d 1e1
24 sur SS 23/03/2013 17:4S
-C, --cvs-exclude
This is a useIuI shorIhand Ior excIuding a broad range oI IiIes IhaI you oIIen don'I wanI
Io IransIer beIween sysIems. !I uses a simiIar aIgoriIhm Io CVS Io deIermine iI a IiIe
shouId be ignored.
The excIude IisI is iniIiaIized Io excIude Ihe IoIIowing iIems (Ihese iniIiaI iIems are
marked as perishabIe -- see Ihe !LTR RULS secIion):
RCS SCCS CvS CvS.adm RCSL00 cvslo.* las TA0S .make.slale .nse_dep1nio *~ #* .#*
,* _$* *$ *.old *.bak *.BAK *.or1 *.re .del-* *.a *.olb *.o *.ob *.so *.exe
*.Z *.elc *.ln core .svn1 .1l1 .h1 .bzr1
Ihen, IiIes IisIed in a $HOM/.cvsignore are added Io Ihe IisI and any IiIes IisIed in Ihe
CVS!CNOR environmenI variabIe (aII cvsignore names are deIimiIed by whiIespace).
inaIIy, any IiIe is ignored iI iI is in Ihe same direcIory as a .cvsignore IiIe and maIches
one oI Ihe paIIerns IisIed Iherein. UnIike rsync's IiIIer/excIude IiIes, Ihese paIIerns are
spIiI on whiIespace. See Ihe cvs(1) manuaI Ior more inIormaIion.
!I you're combining -C wiIh your own --filter ruIes, you shouId noIe IhaI Ihese CVS
excIudes are appended aI Ihe end oI your own ruIes, regardIess oI where Ihe -C was
pIaced on Ihe command-Iine. This makes Ihem a Iower prioriIy Ihan any ruIes you
speciIied expIiciIIy. !I you wanI Io conIroI where Ihese CVS excIudes geI inserIed inIo
your IiIIer ruIes, you shouId omiI Ihe -C as a command-Iine opIion and use a
combinaIion oI --filter=:C and --filter=-C (eiIher on your command-Iine or by puIIing
Ihe ":C" and "-C" ruIes inIo a IiIIer IiIe wiIh your oIher ruIes). The IirsI opIion Iurns on
Ihe per-direcIory scanning Ior Ihe .cvsignore IiIe. The second opIion does a one-Iime
imporI oI Ihe CVS excIudes menIioned above.
-f, --filter=RULL
This opIion aIIows you Io add ruIes Io seIecIiveIy excIude cerIain IiIes Irom Ihe IisI oI
IiIes Io be IransIerred. This is mosI useIuI in combinaIion wiIh a recursive IransIer.
You may use as many --filter opIions on Ihe command Iine as you Iike Io buiId up Ihe
IisI oI IiIes Io excIude. !I Ihe IiIIer conIains whiIespace, be sure Io guoIe iI so IhaI Ihe
sheII gives Ihe ruIe Io rsync as a singIe argumenI. The IexI beIow aIso menIions IhaI
you can use an underscore Io repIace Ihe space IhaI separaIes a ruIe Irom iIs arg.
See Ihe !LTR RULS secIion Ior deIaiIed inIormaIion on Ihis opIion.
-F
The -F opIion is a shorIhand Ior adding Iwo --filter ruIes Io your command. The IirsI
Iime iI is used is a shorIhand Ior Ihis ruIe:
--i1ller=`d1r-mere 1.rsync-i1ller`
This IeIIs rsync Io Iook Ior per-direcIory .rsync-IiIIer IiIes IhaI have been sprinkIed
Ihrough Ihe hierarchy and use Iheir ruIes Io IiIIer Ihe IiIes in Ihe IransIer. !I -F is
repeaIed, iI is a shorIhand Ior Ihis ruIe:
--i1ller=`exclude .rsync-i1ller`
This IiIIers ouI Ihe .rsync-IiIIer IiIes IhemseIves Irom Ihe IransIer.
See Ihe !LTR RULS secIion Ior deIaiIed inIormaIion on how Ihese opIions work.
--exclude=PATTLRN
This opIion is a simpIiIied Iorm oI Ihe --filter opIion IhaI deIauIIs Io an excIude ruIe
and does noI aIIow Ihe IuII ruIe-parsing synIax oI normaI IiIIer ruIes.
--exclude-from=FILL
2S sur SS 23/03/2013 17:4S
This opIion is reIaIed Io Ihe --exclude opIion, buI iI speciIies a !L IhaI conIains
excIude paIIerns (one per Iine). 8Iank Iines in Ihe IiIe and Iines sIarIing wiIh ';' or '#'
are ignored. !I F|L is -, Ihe IisI wiII be read Irom sIandard inpuI.
--include=PATTLRN
This opIion is a simpIiIied Iorm oI Ihe --filter opIion IhaI deIauIIs Io an incIude ruIe
and does noI aIIow Ihe IuII ruIe-parsing synIax oI normaI IiIIer ruIes.
--include-from=FILL
This opIion is reIaIed Io Ihe --include opIion, buI iI speciIies a !L IhaI conIains
incIude paIIerns (one per Iine). 8Iank Iines in Ihe IiIe and Iines sIarIing wiIh ';' or '#' are
ignored. !I F|L is -, Ihe IisI wiII be read Irom sIandard inpuI.
--files-from=FILL
Using Ihis opIion aIIows you Io speciIy Ihe exacI IisI oI IiIes Io IransIer (as read Irom
Ihe speciIied !L or - Ior sIandard inpuI). !I aIso Iweaks Ihe deIauII behavior oI rsync
Io make IransIerring |usI Ihe speciIied IiIes and direcIories easier:
o
The --relative (-R) opIion is impIied, which preserves Ihe paIh inIormaIion
IhaI is speciIied Ior each iIem in Ihe IiIe (use --no-relative or --no-R iI you
wanI Io Iurn IhaI oII).
o
The --dirs (-d) opIion is impIied, which wiII creaIe direcIories speciIied in
Ihe IisI on Ihe desIinaIion raIher Ihan noisiIy skipping Ihem (use --no-dirs or
--no-d iI you wanI Io Iurn IhaI oII).
o
The --archive (-a) opIion's behavior does noI impIy --recursive (-r), so
speciIy iI expIiciIIy, iI you wanI iI.
o
These side-eIIecIs change Ihe deIauII sIaIe oI rsync, so Ihe posiIion oI Ihe
--files-from opIion on Ihe command-Iine has no bearing on how oIher
opIions are parsed (e.g. -a works Ihe same beIore or aIIer --files-from, as
does --no-R and aII oIher opIions).
The IiIenames IhaI are read Irom Ihe !L are aII reIaIive Io Ihe source dir -- any
Ieading sIashes are removed and no ".." reIerences are aIIowed Io go higher Ihan Ihe
source dir. or exampIe, Iake Ihis command:
rsync -a --i1les-irom=1lmp1ioo 1usr remole.1backup
!I /Imp/Ioo conIains Ihe sIring "bin" (or even "/bin"), Ihe /usr/bin direcIory wiII be
creaIed as /backup/bin on Ihe remoIe hosI. !I iI conIains "bin/" (noIe Ihe IraiIing sIash),
Ihe immediaIe conIenIs oI Ihe direcIory wouId aIso be senI (wiIhouI needing Io be
expIiciIIy menIioned in Ihe IiIe -- Ihis began in version 2.6.4). !n boIh cases, iI Ihe -r
opIion was enabIed, IhaI dir's enIire hierarchy wouId aIso be IransIerred (keep in mind
IhaI -r needs Io be speciIied expIiciIIy wiIh --files-from, since iI is noI impIied by -a).
AIso noIe IhaI Ihe eIIecI oI Ihe (enabIed by deIauII) --relative opIion is Io dupIicaIe
onIy Ihe paIh inIo IhaI is read Irom Ihe IiIe -- iI does noI Iorce Ihe dupIicaIion oI Ihe
source-spec paIh (/usr in Ihis case).
!n addiIion, Ihe --files-from IiIe can be read Irom Ihe remoIe hosI insIead oI Ihe IocaI
hosI iI you speciIy a "hosI:" in IronI oI Ihe IiIe (Ihe hosI musI maIch one end oI Ihe
26 sur SS 23/03/2013 17:4S
IransIer). As a shorI-cuI, you can speciIy |usI a preIix oI ":" Io mean "use Ihe remoIe
end oI Ihe IransIer". or exampIe:
rsync -a --i1les-irom=.1palh1i1le-l1sl src.1 1lmp1copy
This wouId copy aII Ihe IiIes speciIied in Ihe /paIh/IiIe-IisI IiIe IhaI was IocaIed on Ihe
remoIe "src" hosI.
!I Ihe --iconv and --protect-args opIions are speciIied and Ihe --files-from IiIenames
are being senI Irom one hosI Io anoIher, Ihe IiIenames wiII be IransIaIed Irom Ihe
sending hosI's charseI Io Ihe receiving hosI's charseI.
NOT: sorIing Ihe IisI oI IiIes in Ihe --IiIes-Irom inpuI heIps rsync Io be more eIIicienI,
as iI wiII avoid re-visiIing Ihe paIh eIemenIs IhaI are shared beIween ad|acenI enIries.
!I Ihe inpuI is noI sorIed, some paIh eIemenIs (impIied direcIories) may end up being
scanned muIIipIe Iimes, and rsync wiII evenIuaIIy undupIicaIe Ihem aIIer Ihey geI
Iurned inIo IiIe-IisI eIemenIs.
-0, --from0
This IeIIs rsync IhaI Ihe ruIes/IiIenames iI reads Irom a IiIe are IerminaIed by a nuII
('\0') characIer, noI a NL, CR, or CRL. This aIIecIs --exclude-from, --include-from,
--files-from, and any merged IiIes speciIied in a --filter ruIe. !I does noI aIIecI --cvs-
exclude (since aII names read Irom a .cvsignore IiIe are spIiI on whiIespace).
-s, --protect-args
This opIion sends aII IiIenames and mosI opIions Io Ihe remoIe rsync wiIhouI aIIowing
Ihe remoIe sheII Io inIerpreI Ihem. This means IhaI spaces are noI spIiI in names, and
any non-wiIdcard speciaI characIers are noI IransIaIed (such as ~, $, ;, &, eIc.).
WiIdcards are expanded on Ihe remoIe hosI by rsync (insIead oI Ihe sheII doing iI).
!I you use Ihis opIion wiIh --iconv, Ihe args reIaIed Io Ihe remoIe side wiII aIso be
IransIaIed Irom Ihe IocaI Io Ihe remoIe characIer-seI. The IransIaIion happens beIore
wiId-cards are expanded. See aIso Ihe --files-from opIion.
-T, --temp-dir=DIR
This opIion insIrucIs rsync Io use D!R as a scraIch direcIory when creaIing Iemporary
copies oI Ihe IiIes IransIerred on Ihe receiving side. The deIauII behavior is Io creaIe
each Iemporary IiIe in Ihe same direcIory as Ihe associaIed desIinaIion IiIe.
This opIion is mosI oIIen used when Ihe receiving disk parIiIion does noI have enough
Iree space Io hoId a copy oI Ihe IargesI IiIe in Ihe IransIer. !n Ihis case (i.e. when Ihe
scraIch direcIory is on a diIIerenI disk parIiIion), rsync wiII noI be abIe Io rename each
received Iemporary IiIe over Ihe Iop oI Ihe associaIed desIinaIion IiIe, buI insIead musI
copy iI inIo pIace. Rsync does Ihis by copying Ihe IiIe over Ihe Iop oI Ihe desIinaIion
IiIe, which means IhaI Ihe desIinaIion IiIe wiII conIain IruncaIed daIa during Ihis copy.
!I Ihis were noI done Ihis way (even iI Ihe desIinaIion IiIe were IirsI removed, Ihe daIa
IocaIIy copied Io a Iemporary IiIe in Ihe desIinaIion direcIory, and Ihen renamed inIo
pIace) iI wouId be possibIe Ior Ihe oId IiIe Io conIinue Iaking up disk space (iI someone
had iI open), and Ihus Ihere mighI noI be enough room Io IiI Ihe new version on Ihe
disk aI Ihe same Iime.
!I you are using Ihis opIion Ior reasons oIher Ihan a shorIage oI disk space, you may
wish Io combine iI wiIh Ihe --delay-updates opIion, which wiII ensure IhaI aII copied
IiIes geI puI inIo subdirecIories in Ihe desIinaIion hierarchy, awaiIing Ihe end oI Ihe
IransIer. !I you don'I have enough room Io dupIicaIe aII Ihe arriving IiIes on Ihe
desIinaIion parIiIion, anoIher way Io IeII rsync IhaI you aren'I overIy concerned abouI
disk space is Io use Ihe --partial-dir opIion wiIh a reIaIive paIh; because Ihis IeIIs rsync
27 sur SS 23/03/2013 17:4S
IhaI iI is OK Io sIash oII a copy oI a singIe IiIe in a subdir in Ihe desIinaIion hierarchy,
rsync wiII use Ihe parIiaI-dir as a sIaging area Io bring over Ihe copied IiIe, and Ihen
rename iI inIo pIace Irom Ihere. (SpeciIying a --partial-dir wiIh an absoIuIe paIh does
noI have Ihis side-eIIecI.)
-y, --fuzzy
This opIion IeIIs rsync IhaI iI shouId Iook Ior a basis IiIe Ior any desIinaIion IiIe IhaI is
missing. The currenI aIgoriIhm Iooks in Ihe same direcIory as Ihe desIinaIion IiIe Ior
eiIher a IiIe IhaI has an idenIicaI size and modiIied-Iime, or a simiIarIy-named IiIe. !I
Iound, rsync uses Ihe Iuzzy basis IiIe Io Iry Io speed up Ihe IransIer.
NoIe IhaI Ihe use oI Ihe --delete opIion mighI geI rid oI any poIenIiaI Iuzzy-maIch IiIes,
so eiIher use --delete-after or speciIy some IiIename excIusions iI you need Io prevenI
Ihis.
--compare-dest=DIR
This opIion insIrucIs rsync Io use D|R on Ihe desIinaIion machine as an addiIionaI
hierarchy Io compare desIinaIion IiIes againsI doing IransIers (iI Ihe IiIes are missing
in Ihe desIinaIion direcIory). !I a IiIe is Iound in D|R IhaI is idenIicaI Io Ihe sender's IiIe,
Ihe IiIe wiII NOT be IransIerred Io Ihe desIinaIion direcIory. This is useIuI Ior creaIing a
sparse backup oI |usI IiIes IhaI have changed Irom an earIier backup.
8eginning in version 2.6.4, muIIipIe --compare-dest direcIories may be provided,
which wiII cause rsync Io search Ihe IisI in Ihe order speciIied Ior an exacI maIch. !I a
maIch is Iound IhaI diIIers onIy in aIIribuIes, a IocaI copy is made and Ihe aIIribuIes
updaIed. !I a maIch is noI Iound, a basis IiIe Irom one oI Ihe D|Rs wiII be seIecIed Io Iry
Io speed up Ihe IransIer.
!I D|R is a reIaIive paIh, iI is reIaIive Io Ihe desIinaIion direcIory. See aIso --copy-dest
and --link-dest.
--copy-dest=DIR
This opIion behaves Iike --compare-dest, buI rsync wiII aIso copy unchanged IiIes
Iound in D|R Io Ihe desIinaIion direcIory using a IocaI copy. This is useIuI Ior doing
IransIers Io a new desIinaIion whiIe Ieaving exisIing IiIes inIacI, and Ihen doing a
IIash-cuIover when aII IiIes have been successIuIIy IransIerred.
MuIIipIe --copy-dest direcIories may be provided, which wiII cause rsync Io search Ihe
IisI in Ihe order speciIied Ior an unchanged IiIe. !I a maIch is noI Iound, a basis IiIe
Irom one oI Ihe D|Rs wiII be seIecIed Io Iry Io speed up Ihe IransIer.
!I D|R is a reIaIive paIh, iI is reIaIive Io Ihe desIinaIion direcIory. See aIso
--compare-dest and --link-dest.
--link-dest=DIR
This opIion behaves Iike --copy-dest, buI unchanged IiIes are hard Iinked Irom D|R Io
Ihe desIinaIion direcIory. The IiIes musI be idenIicaI in aII preserved aIIribuIes (e.g.
permissions, possibIy ownership) in order Ior Ihe IiIes Io be Iinked IogeIher. An
exampIe:
rsync -av --l1nk-desl=$PW01pr1or_d1r hosl.src_d1r1 neW_d1r1
!I IiIe's aren'I Iinking, doubIe-check Iheir aIIribuIes. AIso check iI some aIIribuIes are
geIIing Iorced ouIside oI rsync's conIroI, such a mounI opIion IhaI sguishes rooI Io a
singIe user, or mounIs a removabIe drive wiIh generic ownership (such as OS X's
"!gnore ownership on Ihis voIume" opIion).
8eginning in version 2.6.4, muIIipIe --link-dest direcIories may be provided, which wiII
cause rsync Io search Ihe IisI in Ihe order speciIied Ior an exacI maIch. !I a maIch is
28 sur SS 23/03/2013 17:4S
Iound IhaI diIIers onIy in aIIribuIes, a IocaI copy is made and Ihe aIIribuIes updaIed. !I
a maIch is noI Iound, a basis IiIe Irom one oI Ihe D|Rs wiII be seIecIed Io Iry Io speed up
Ihe IransIer.
This opIion works besI when copying inIo an empIy desIinaIion hierarchy, as rsync
IreaIs exisIing IiIes as deIiniIive (so iI never Iooks in Ihe Iink-desI dirs when a
desIinaIion IiIe aIready exisIs), and as maIIeabIe (so iI mighI change Ihe aIIribuIes oI a
desIinaIion IiIe, which aIIecIs aII Ihe hard-Iinked versions).
NoIe IhaI iI you combine Ihis opIion wiIh --ignore-times, rsync wiII noI Iink any IiIes
IogeIher because iI onIy Iinks idenIicaI IiIes IogeIher as a subsIiIuIe Ior IransIerring Ihe
IiIe, never as an addiIionaI check aIIer Ihe IiIe is updaIed.
!I D|R is a reIaIive paIh, iI is reIaIive Io Ihe desIinaIion direcIory. See aIso
--compare-dest and --copy-dest.
NoIe IhaI rsync versions prior Io 2.6.1 had a bug IhaI couId prevenI --link-dest Irom
working properIy Ior a non-super-user when -o was speciIied (or impIied by -a). You
can work-around Ihis bug by avoiding Ihe -o opIion when sending Io an oId rsync.
-z, --compress
WiIh Ihis opIion, rsync compresses Ihe IiIe daIa as iI is senI Io Ihe desIinaIion machine,
which reduces Ihe amounI oI daIa being IransmiIIed -- someIhing IhaI is useIuI over a
sIow connecIion.
NoIe IhaI Ihis opIion IypicaIIy achieves beIIer compression raIios Ihan can be achieved
by using a compressing remoIe sheII or a compressing IransporI because iI Iakes
advanIage oI Ihe impIiciI inIormaIion in Ihe maIching daIa bIocks IhaI are noI
expIiciIIy senI over Ihe connecIion.
See Ihe --skip-compress opIion Ior Ihe deIauII IisI oI IiIe suIIixes IhaI wiII noI be
compressed.
--compress-level=NUM
xpIiciIIy seI Ihe compression IeveI Io use (see --compress) insIead oI IeIIing iI deIauII.
!I NUM is non-zero, Ihe --compress opIion is impIied.
--skip-compress=LIST
Override Ihe IisI oI IiIe suIIixes IhaI wiII noI be compressed. The LIST shouId be one or
more IiIe suIIixes (wiIhouI Ihe doI) separaIed by sIashes (/).
You may speciIy an empIy sIring Io indicaIe IhaI no IiIe shouId be skipped.
SimpIe characIer-cIass maIching is supporIed: each musI consisI oI a IisI oI IeIIers
inside Ihe sguare brackeIs (e.g. no speciaI cIasses, such as "[:aIpha:]", are supporIed,
and '-' has no speciaI meaning).
The characIers asIerisk (") and guesIion-mark (?) have no speciaI meaning.
Here's an exampIe IhaI speciIies 6 suIIixes Io skip (since 1 oI Ihe S ruIes maIches 2
suIIixes):
--sk1p-compress=z1p1mp|34]17z1bz2
The deIauII IisI oI suIIixes IhaI wiII noI be compressed is Ihis (in Ihis version oI rsync):
7z avi bz2 deb gz iso jpeg jpg mov mp3 mp4 ogg rpm tbz tgz z zip
This IisI wiII be repIaced by your --skip-compress IisI in aII buI one siIuaIion: a copy
Irom a daemon rsync wiII add your skipped suIIixes Io iIs IisI oI non-compressing IiIes
(and iIs IisI may be conIigured Io a diIIerenI deIauII).
--numeric-ids
WiIh Ihis opIion rsync wiII IransIer numeric group and user !Ds raIher Ihan using user
29 sur SS 23/03/2013 17:4S
and group names and mapping Ihem aI boIh ends.
8y deIauII rsync wiII use Ihe username and groupname Io deIermine whaI ownership
Io give IiIes. The speciaI uid 0 and Ihe speciaI group 0 are never mapped via user/group
names even iI Ihe --numeric-ids opIion is noI speciIied.
!I a user or group has no name on Ihe source sysIem or iI has no maIch on Ihe
desIinaIion sysIem, Ihen Ihe numeric !D Irom Ihe source sysIem is used insIead. See
aIso Ihe commenIs on Ihe "use chrooI" seIIing in Ihe rsyncd.conI manpage Ior
inIormaIion on how Ihe chrooI seIIing aIIecIs rsync's abiIiIy Io Iook up Ihe names oI
Ihe users and groups and whaI you can do abouI iI.
--timeout=TIMLOUT
This opIion aIIows you Io seI a maximum !/O IimeouI in seconds. !I no daIa is
IransIerred Ior Ihe speciIied Iime Ihen rsync wiII exiI. The deIauII is 0, which means no
IimeouI.
--contimeout
This opIion aIIows you Io seI Ihe amounI oI Iime IhaI rsync wiII waiI Ior iIs connecIion
Io an rsync daemon Io succeed. !I Ihe IimeouI is reached, rsync exiIs wiIh an error.
--address
8y deIauII rsync wiII bind Io Ihe wiIdcard address when connecIing Io an rsync
daemon. The --address opIion aIIows you Io speciIy a speciIic !P address (or hosIname)
Io bind Io. See aIso Ihis opIion in Ihe --daemon mode secIion.
--port=PORT
This speciIies an aIIernaIe TCP porI number Io use raIher Ihan Ihe deIauII oI 873. This
is onIy needed iI you are using Ihe doubIe-coIon (::) synIax Io connecI wiIh an rsync
daemon (since Ihe URL synIax has a way Io speciIy Ihe porI as a parI oI Ihe URL). See
aIso Ihis opIion in Ihe --daemon mode secIion.
--sockopts
This opIion can provide endIess Iun Ior peopIe who Iike Io Iune Iheir sysIems Io Ihe
uImosI degree. You can seI aII sorIs oI sockeI opIions which may make IransIers IasIer
(or sIower!). Read Ihe man page Ior Ihe selsockopl{} sysIem caII Ior deIaiIs on some oI
Ihe opIions you may be abIe Io seI. 8y deIauII no speciaI sockeI opIions are seI. This
onIy aIIecIs direcI sockeI connecIions Io a remoIe rsync daemon. This opIion aIso exisIs
in Ihe --daemon mode secIion.
--blocking-io
This IeIIs rsync Io use bIocking !/O when Iaunching a remoIe sheII IransporI. !I Ihe
remoIe sheII is eiIher rsh or remsh, rsync deIauIIs Io using bIocking !/O, oIherwise iI
deIauIIs Io using non-bIocking !/O. (NoIe IhaI ssh preIers non-bIocking !/O.)
-i, --itemize-changes
ReguesIs a simpIe iIemized IisI oI Ihe changes IhaI are being made Io each IiIe,
incIuding aIIribuIe changes. This is exacIIy Ihe same as speciIying --out-format='%i
%n%L'. !I you repeaI Ihe opIion, unchanged IiIes wiII aIso be ouIpuI, buI onIy iI Ihe
receiving rsync is aI IeasI version 2.6.7 (you can use -vv wiIh oIder versions oI rsync,
buI IhaI aIso Iurns on Ihe ouIpuI oI oIher verbose messages).
The "%i" escape has a crypIic ouIpuI IhaI is 11 IeIIers Iong. The generaI IormaI is Iike
Ihe sIring YXcstpoguax, where Y is repIaced by Ihe Iype oI updaIe being done, X is
repIaced by Ihe IiIe-Iype, and Ihe oIher IeIIers represenI aIIribuIes IhaI may be ouIpuI
iI Ihey are being modiIied.
The updaIe Iypes IhaI repIace Ihe Y are as IoIIows:
o
30 sur SS 23/03/2013 17:4S
A < means IhaI a IiIe is being IransIerred Io Ihe remoIe hosI (senI).
o
A > means IhaI a IiIe is being IransIerred Io Ihe IocaI hosI (received).
o
A c means IhaI a IocaI change/creaIion is occurring Ior Ihe iIem (such as Ihe
creaIion oI a direcIory or Ihe changing oI a symIink, eIc.).
o
A h means IhaI Ihe iIem is a hard Iink Io anoIher iIem (reguires --hard-
links).
o
A . means IhaI Ihe iIem is noI being updaIed (Ihough iI mighI have aIIribuIes
IhaI are being modiIied).
o
A * means IhaI Ihe resI oI Ihe iIemized-ouIpuI area conIains a message (e.g.
"deIeIing").
The IiIe-Iypes IhaI repIace Ihe X are: f Ior a IiIe, a d Ior a direcIory, an L Ior a symIink,
a D Ior a device, and a S Ior a speciaI IiIe (e.g. named sockeIs and IiIos).
The oIher IeIIers in Ihe sIring above are Ihe acIuaI IeIIers IhaI wiII be ouIpuI iI Ihe
associaIed aIIribuIe Ior Ihe iIem is being updaIed or a "." Ior no change. Three
excepIions Io Ihis are: (1) a newIy creaIed iIem repIaces each IeIIer wiIh a "", (2) an
idenIicaI iIem repIaces Ihe doIs wiIh spaces, and (3) an unknown aIIribuIe repIaces
each IeIIer wiIh a "?" (Ihis can happen when IaIking Io an oIder rsync).
The aIIribuIe IhaI is associaIed wiIh each IeIIer is as IoIIows:
o
A c means eiIher IhaI a reguIar IiIe has a diIIerenI checksum (reguires
--checksum) or IhaI a symIink, device, or speciaI IiIe has a changed vaIue.
NoIe IhaI iI you are sending IiIes Io an rsync prior Io 3.0.1, Ihis change IIag
wiII be presenI onIy Ior checksum-diIIering reguIar IiIes.
o
A s means Ihe size oI a reguIar IiIe is diIIerenI and wiII be updaIed by Ihe
IiIe IransIer.
o
A t means Ihe modiIicaIion Iime is diIIerenI and is being updaIed Io Ihe
sender's vaIue (reguires --times). An aIIernaIe vaIue oI T means IhaI Ihe
modiIicaIion Iime wiII be seI Io Ihe IransIer Iime, which happens when a
IiIe/symIink/device is updaIed wiIhouI --times and when a symIink is
changed and Ihe receiver can'I seI iIs Iime. (NoIe: when using an rsync 3.0.0
cIienI, you mighI see Ihe s IIag combined wiIh t insIead oI Ihe proper T IIag
Ior Ihis Iime-seIIing IaiIure.)
o
A p means Ihe permissions are diIIerenI and are being updaIed Io Ihe
sender's vaIue (reguires --perms).
o
An o means Ihe owner is diIIerenI and is being updaIed Io Ihe sender's vaIue
(reguires --owner and super-user priviIeges).
o
A g means Ihe group is diIIerenI and is being updaIed Io Ihe sender's vaIue
31 sur SS 23/03/2013 17:4S
(reguires --group and Ihe auIhoriIy Io seI Ihe group).
o
The u sIoI is reserved Ior IuIure use.
o
The a means IhaI Ihe ACL inIormaIion changed.
o
The x means IhaI Ihe exIended aIIribuIe inIormaIion changed.
One oIher ouIpuI is possibIe: when deIeIing IiIes, Ihe "%i" wiII ouIpuI Ihe sIring
""deIeIing" Ior each iIem IhaI is being removed (assuming IhaI you are IaIking Io a
recenI enough rsync IhaI iI Iogs deIeIions insIead oI ouIpuIIing Ihem as a verbose
message).
--out-format=FORMAT
This aIIows you Io speciIy exacIIy whaI Ihe rsync cIienI ouIpuIs Io Ihe user on a
per-updaIe basis. The IormaI is a IexI sIring conIaining embedded singIe-characIer
escape seguences preIixed wiIh a percenI (%) characIer. A deIauII IormaI oI "%n%L" is
assumed iI -v is speciIied (which reporIs Ihe name oI Ihe IiIe and, iI Ihe iIem is a Iink,
where iI poinIs). or a IuII IisI oI Ihe possibIe escape characIers, see Ihe "Iog IormaI"
seIIing in Ihe rsyncd.conI manpage.
SpeciIying Ihe --out-format opIion wiII menIion each IiIe, dir, eIc. IhaI geIs updaIed in
a signiIicanI way (a IransIerred IiIe, a recreaIed symIink/device, or a Iouched
direcIory). !n addiIion, iI Ihe iIemize-changes escape (%i) is incIuded in Ihe sIring (e.g.
iI Ihe --itemize-changes opIion was used), Ihe Iogging oI names increases Io menIion
any iIem IhaI is changed in any way (as Iong as Ihe receiving side is aI IeasI 2.6.4). See
Ihe --itemize-changes opIion Ior a descripIion oI Ihe ouIpuI oI "%i".
Rsync wiII ouIpuI Ihe ouI-IormaI sIring prior Io a IiIe's IransIer unIess one oI Ihe
IransIer-sIaIisIic escapes is reguesIed, in which case Ihe Iogging is done aI Ihe end oI
Ihe IiIe's IransIer. When Ihis IaIe Iogging is in eIIecI and --progress is aIso speciIied,
rsync wiII aIso ouIpuI Ihe name oI Ihe IiIe being IransIerred prior Io iIs progress
inIormaIion (IoIIowed, oI course, by Ihe ouI-IormaI ouIpuI).
--log-file=FILL
This opIion causes rsync Io Iog whaI iI is doing Io a IiIe. This is simiIar Io Ihe Iogging
IhaI a daemon does, buI can be reguesIed Ior Ihe cIienI side and/or Ihe server side oI a
non-daemon IransIer. !I speciIied as a cIienI opIion, IransIer Iogging wiII be enabIed
wiIh a deIauII IormaI oI "%i %n%L". See Ihe --log-file-format opIion iI you wish Io
override Ihis.
Here's a exampIe command IhaI reguesIs Ihe remoIe side Io Iog whaI is happening:
rsync -av --rsync-palh="rsync --lo-i1le=1lmp1rlo" src1 desl1
This is very useIuI iI you need Io debug why a connecIion is cIosing unexpecIedIy.
--log-file-format=FORMAT
This aIIows you Io speciIy exacIIy whaI per-updaIe Iogging is puI inIo Ihe IiIe speciIied
by Ihe --log-file opIion (which musI aIso be speciIied Ior Ihis opIion Io have any eIIecI).
!I you speciIy an empIy sIring, updaIed IiIes wiII noI be menIioned in Ihe Iog IiIe. or a
IisI oI Ihe possibIe escape characIers, see Ihe "Iog IormaI" seIIing in Ihe rsyncd.conI
manpage.
The deIauII ORMAT used iI --log-file is speciIied and Ihis opIion is noI is '%i %n%L'.
--stats
32 sur SS 23/03/2013 17:4S
This IeIIs rsync Io prinI a verbose seI oI sIaIisIics on Ihe IiIe IransIer, aIIowing you Io
IeII how eIIecIive rsync's deIIa-IransIer aIgoriIhm is Ior your daIa.
The currenI sIaIisIics are as IoIIows:
o
Number of files is Ihe counI oI aII "IiIes" (in Ihe generic sense), which
incIudes direcIories, symIinks, eIc.
o
Number of files transferred is Ihe counI oI normaI IiIes IhaI were updaIed
via rsync's deIIa-IransIer aIgoriIhm, which does noI incIude creaIed dirs,
symIinks, eIc.
o
Total file size is Ihe IoIaI sum oI aII IiIe sizes in Ihe IransIer. This does noI
counI any size Ior direcIories or speciaI IiIes, buI does incIude Ihe size oI
symIinks.
o
Total transferred file size is Ihe IoIaI sum oI aII IiIes sizes Ior |usI Ihe
IransIerred IiIes.
o
Literal data is how much unmaIched IiIe-updaIe daIa we had Io send Io Ihe
receiver Ior iI Io recreaIe Ihe updaIed IiIes.
o
Matched data is how much daIa Ihe receiver goI IocaIIy when recreaIing
Ihe updaIed IiIes.
o
File list size is how big Ihe IiIe-IisI daIa was when Ihe sender senI iI Io Ihe
receiver. This is smaIIer Ihan Ihe in-memory size Ior Ihe IiIe IisI due Io some
compressing oI dupIicaIed daIa when rsync sends Ihe IisI.
o
File list generation time is Ihe number oI seconds IhaI Ihe sender spenI
creaIing Ihe IiIe IisI. This reguires a modern rsync on Ihe sending side Ior
Ihis Io be presenI.
o
File list transfer time is Ihe number oI seconds IhaI Ihe sender spenI
sending Ihe IiIe IisI Io Ihe receiver.
o
Total bytes sent is Ihe counI oI aII Ihe byIes IhaI rsync senI Irom Ihe cIienI
side Io Ihe server side.
o
Total bytes received is Ihe counI oI aII non-message byIes IhaI rsync
received by Ihe cIienI side Irom Ihe server side. "Non-message" byIes means
IhaI we don'I counI Ihe byIes Ior a verbose message IhaI Ihe server senI Io
us, which makes Ihe sIaIs more consisIenI.
-8, --8-bit-output
This IeIIs rsync Io Ieave aII high-biI characIers unescaped in Ihe ouIpuI insIead oI
Irying Io IesI Ihem Io see iI Ihey're vaIid in Ihe currenI IocaIe and escaping Ihe invaIid
ones. AII conIroI characIers (buI never Iabs) are aIways escaped, regardIess oI Ihis
opIion's seIIing.
33 sur SS 23/03/2013 17:4S
The escape idiom IhaI sIarIed in 2.6.7 is Io ouIpuI a IiIeraI backsIash (\) and a hash (#),
IoIIowed by exacIIy 3 ocIaI digiIs. or exampIe, a newIine wouId ouIpuI as "\#012". A
IiIeraI backsIash IhaI is in a IiIename is noI escaped unIess iI is IoIIowed by a hash and
3 digiIs (0-9).
-h, --human-readable
OuIpuI numbers in a more human-readabIe IormaI. This makes big numbers ouIpuI
using Iarger uniIs, wiIh a K, M, or C suIIix. !I Ihis opIion was speciIied once, Ihese uniIs
are K (1000), M (1000"1000), and C (1000"1000"1000); iI Ihe opIion is repeaIed, Ihe
uniIs are powers oI 1024 insIead oI 1000.
--partial
8y deIauII, rsync wiII deIeIe any parIiaIIy IransIerred IiIe iI Ihe IransIer is inIerrupIed.
!n some circumsIances iI is more desirabIe Io keep parIiaIIy IransIerred IiIes. Using Ihe
--partial opIion IeIIs rsync Io keep Ihe parIiaI IiIe which shouId make a subseguenI
IransIer oI Ihe resI oI Ihe IiIe much IasIer.
--partial-dir=DIR
A beIIer way Io keep parIiaI IiIes Ihan Ihe --partial opIion is Io speciIy a D|R IhaI wiII
be used Io hoId Ihe parIiaI daIa (insIead oI wriIing iI ouI Io Ihe desIinaIion IiIe). On Ihe
nexI IransIer, rsync wiII use a IiIe Iound in Ihis dir as daIa Io speed up Ihe resumpIion
oI Ihe IransIer and Ihen deIeIe iI aIIer iI has served iIs purpose.
NoIe IhaI iI --whole-file is speciIied (or impIied), any parIiaI-dir IiIe IhaI is Iound Ior a
IiIe IhaI is being updaIed wiII simpIy be removed (since rsync is sending IiIes wiIhouI
using rsync's deIIa-IransIer aIgoriIhm).
Rsync wiII creaIe Ihe D|R iI iI is missing (|usI Ihe IasI dir -- noI Ihe whoIe paIh). This
makes iI easy Io use a reIaIive paIh (such as "--partial-dir=.rsync-partial") Io have
rsync creaIe Ihe parIiaI-direcIory in Ihe desIinaIion IiIe's direcIory when needed, and
Ihen remove iI again when Ihe parIiaI IiIe is deIeIed.
!I Ihe parIiaI-dir vaIue is noI an absoIuIe paIh, rsync wiII add an excIude ruIe aI Ihe
end oI aII your exisIing excIudes. This wiII prevenI Ihe sending oI any parIiaI-dir IiIes
IhaI may exisI on Ihe sending side, and wiII aIso prevenI Ihe unIimeIy deIeIion oI
parIiaI-dir iIems on Ihe receiving side. An exampIe: Ihe above --partial-dir opIion
wouId add Ihe eguivaIenI oI "-f '-p .rsync-partialj'" aI Ihe end oI any oIher IiIIer ruIes.
!I you are suppIying your own excIude ruIes, you may need Io add your own
excIude/hide/proIecI ruIe Ior Ihe parIiaI-dir because (1) Ihe auIo-added ruIe may be
ineIIecIive aI Ihe end oI your oIher ruIes, or (2) you may wish Io override rsync's
excIude choice. or insIance, iI you wanI Io make rsync cIean-up any IeII-over
parIiaI-dirs IhaI may be Iying around, you shouId speciIy --delete-after and add a
"risk" IiIIer ruIe, e.g. -f 'R .rsync-partialj'. (Avoid using --delete-before or --delete-
during unIess you don'I need rsync Io use any oI Ihe IeII-over parIiaI-dir daIa during
Ihe currenI run.)
!MPORTANT: Ihe --partial-dir shouId noI be wriIabIe by oIher users or iI is a securiIy
risk. .g. AVO!D "/Imp".
You can aIso seI Ihe parIiaI-dir vaIue Ihe RSYNC_PART!AL_D!R environmenI variabIe.
SeIIing Ihis in Ihe environmenI does noI Iorce --partial Io be enabIed, buI raIher iI
aIIecIs where parIiaI IiIes go when --partial is speciIied. or insIance, insIead oI using
--partial-dir=.rsync-tmp aIong wiIh --progress, you couId seI
RSYNC_PART!AL_D!R=.rsync-Imp in your environmenI and Ihen |usI use Ihe -P opIion
Io Iurn on Ihe use oI Ihe .rsync-Imp dir Ior parIiaI IransIers. The onIy Iimes IhaI Ihe
--partial opIion does noI Iook Ior Ihis environmenI vaIue are (1) when --inplace was
34 sur SS 23/03/2013 17:4S
speciIied (since --inplace conIIicIs wiIh --partial-dir), and (2) when --delay-updates
was speciIied (see beIow).
or Ihe purposes oI Ihe daemon-conIig's "reIuse opIions" seIIing, --partial-dir does not
impIy --partial. This is so IhaI a reIusaI oI Ihe --partial opIion can be used Io disaIIow
Ihe overwriIing oI desIinaIion IiIes wiIh a parIiaI IransIer, whiIe sIiII aIIowing Ihe saIer
idiom provided by --partial-dir.
--delay-updates
This opIion puIs Ihe Iemporary IiIe Irom each updaIed IiIe inIo a hoIding direcIory
unIiI Ihe end oI Ihe IransIer, aI which Iime aII Ihe IiIes are renamed inIo pIace in rapid
succession. This aIIempIs Io make Ihe updaIing oI Ihe IiIes a IiIIIe more aIomic. 8y
deIauII Ihe IiIes are pIaced inIo a direcIory named ".~Imp~" in each IiIe's desIinaIion
direcIory, buI iI you've speciIied Ihe --partial-dir opIion, IhaI direcIory wiII be used
insIead. See Ihe commenIs in Ihe --partial-dir secIion Ior a discussion oI how Ihis
".~Imp~" dir wiII be excIuded Irom Ihe IransIer, and whaI you can do iI you wanI rsync
Io cIeanup oId ".~Imp~" dirs IhaI mighI be Iying around. ConIIicIs wiIh --inplace and
--append.
This opIion uses more memory on Ihe receiving side (one biI per IiIe IransIerred) and
aIso reguires enough Iree disk space on Ihe receiving side Io hoId an addiIionaI copy oI
aII Ihe updaIed IiIes. NoIe aIso IhaI you shouId noI use an absoIuIe paIh Io --partial-dir
unIess (1) Ihere is no chance oI any oI Ihe IiIes in Ihe IransIer having Ihe same name
(since aII Ihe updaIed IiIes wiII be puI inIo a singIe direcIory iI Ihe paIh is absoIuIe) and
(2) Ihere are no mounI poinIs in Ihe hierarchy (since Ihe deIayed updaIes wiII IaiI iI
Ihey can'I be renamed inIo pIace).
See aIso Ihe "aIomic-rsync" perI scripI in Ihe "supporI" subdir Ior an updaIe aIgoriIhm
IhaI is even more aIomic (iI uses --link-dest and a paraIIeI hierarchy oI IiIes).
-m, --prune-empty-dirs
This opIion IeIIs Ihe receiving rsync Io geI rid oI empIy direcIories Irom Ihe IiIe-IisI,
incIuding nesIed direcIories IhaI have no non-direcIory chiIdren. This is useIuI Ior
avoiding Ihe creaIion oI a bunch oI useIess direcIories when Ihe sending rsync is
recursiveIy scanning a hierarchy oI IiIes using incIude/excIude/IiIIer ruIes.
NoIe IhaI Ihe use oI IransIer ruIes, such as Ihe --min-size opIion, does noI aIIecI whaI
goes inIo Ihe IiIe IisI, and Ihus does noI Ieave direcIories empIy, even iI none oI Ihe IiIes
in a direcIory maIch Ihe IransIer ruIe.
8ecause Ihe IiIe-IisI is acIuaIIy being pruned, Ihis opIion aIso aIIecIs whaI direcIories
geI deIeIed when a deIeIe is acIive. However, keep in mind IhaI excIuded IiIes and
direcIories can prevenI exisIing iIems Irom being deIeIed due Io an excIude boIh
hiding source IiIes and proIecIing desIinaIion IiIes. See Ihe perishabIe IiIIer-ruIe opIion
Ior how Io avoid Ihis.
You can prevenI Ihe pruning oI cerIain empIy direcIories Irom Ihe IiIe-IisI by using a
gIobaI "proIecI" IiIIer. or insIance, Ihis opIion wouId ensure IhaI Ihe direcIory
"empIydir" was kepI in Ihe IiIe-IisI:
--IiIIer 'proIecI empIydir/'
Here's an exampIe IhaI copies aII .pdI IiIes in a hierarchy, onIy creaIing Ihe necessary
desIinaIion direcIories Io hoId Ihe .pdI IiIes, and ensures IhaI any superIIuous IiIes and
direcIories in Ihe desIinaIion are removed (noIe Ihe hide IiIIer oI non-direcIories being
used insIead oI an excIude):
rsync -avm --deI --incIude='".pdI' -I 'hide,! "/' src/ desI
3S sur SS 23/03/2013 17:4S
!I you didn'I wanI Io remove superIIuous desIinaIion IiIes, Ihe more Iime-honored
opIions oI "--include='*j' --exclude='*'" wouId work Iine in pIace oI Ihe hide-IiIIer (iI
IhaI is more naIuraI Io you).
--progress
This opIion IeIIs rsync Io prinI inIormaIion showing Ihe progress oI Ihe IransIer. This
gives a bored user someIhing Io waIch. !mpIies --verbose iI iI wasn'I aIready speciIied.
WhiIe rsync is IransIerring a reguIar IiIe, iI updaIes a progress Iine IhaI Iooks Iike Ihis:
782448 637 110.64kB1s 0.00.04
!n Ihis exampIe, Ihe receiver has reconsIrucIed 782448 byIes or 63% oI Ihe sender's
IiIe, which is being reconsIrucIed aI a raIe oI 110.64 kiIobyIes per second, and Ihe
IransIer wiII Iinish in 4 seconds iI Ihe currenI raIe is mainIained unIiI Ihe end.
These sIaIisIics can be misIeading iI rsync's deIIa-IransIer aIgoriIhm is in use. or
exampIe, iI Ihe sender's IiIe consisIs oI Ihe basis IiIe IoIIowed by addiIionaI daIa, Ihe
reporIed raIe wiII probabIy drop dramaIicaIIy when Ihe receiver geIs Io Ihe IiIeraI
daIa, and Ihe IransIer wiII probabIy Iake much Ionger Io Iinish Ihan Ihe receiver
esIimaIed as iI was Iinishing Ihe maIched parI oI Ihe IiIe.
When Ihe IiIe IransIer Iinishes, rsync repIaces Ihe progress Iine wiIh a summary Iine
IhaI Iooks Iike Ihis:
1238099 1007 146.38kB1s 0.00.08 {xier#5, lo-check=1691396}
!n Ihis exampIe, Ihe IiIe was 1238099 byIes Iong in IoIaI, Ihe average raIe oI IransIer Ior
Ihe whoIe IiIe was 146.38 kiIobyIes per second over Ihe 8 seconds IhaI iI Iook Io
compIeIe, iI was Ihe SIh IransIer oI a reguIar IiIe during Ihe currenI rsync session, and
Ihere are 169 more IiIes Ior Ihe receiver Io check (Io see iI Ihey are up-Io-daIe or noI)
remaining ouI oI Ihe 396 IoIaI IiIes in Ihe IiIe-IisI.
-P
The -P opIion is eguivaIenI Io --partial --progress. !Is purpose is Io make iI much
easier Io speciIy Ihese Iwo opIions Ior a Iong IransIer IhaI may be inIerrupIed.
--password-file
This opIion aIIows you Io provide a password in a IiIe Ior accessing an rsync daemon.
The IiIe musI noI be worId readabIe. !I shouId conIain |usI Ihe password as Ihe IirsI
Iine oI Ihe IiIe (aII oIher Iines are ignored).
This opIion does noI suppIy a password Io a remoIe sheII IransporI such as ssh; Io Iearn
how Io do IhaI, consuII Ihe remoIe sheII's documenIaIion. When accessing an rsync
daemon using a remoIe sheII as Ihe IransporI, Ihis opIion onIy comes inIo eIIecI aIIer
Ihe remoIe sheII Iinishes iIs auIhenIicaIion (i.e. iI you have aIso speciIied a password in
Ihe daemon's conIig IiIe).
--list-only
This opIion wiII cause Ihe source IiIes Io be IisIed insIead oI IransIerred. This opIion is
inIerred iI Ihere is a singIe source arg and no desIinaIion speciIied, so iIs main uses
are: (1) Io Iurn a copy command IhaI incIudes a desIinaIion arg inIo a IiIe-IisIing
command, or (2) Io be abIe Io speciIy more Ihan one source arg (noIe: be sure Io
incIude Ihe desIinaIion). CauIion: keep in mind IhaI a source arg wiIh a wiId-card is
expanded by Ihe sheII inIo muIIipIe args, so iI is never saIe Io Iry Io IisI such an arg
wiIhouI using Ihis opIion. or exampIe:
rsync -av --l1sl-only ioo* desl1
36 sur SS 23/03/2013 17:4S
CompaIibiIiIy noIe: when reguesIing a remoIe IisIing oI IiIes Irom an rsync IhaI is
version 2.6.3 or oIder, you may encounIer an error iI you ask Ior a non-recursive
IisIing. This is because a IiIe IisIing impIies Ihe --dirs opIion w/o --recursive, and oIder
rsyncs don'I have IhaI opIion. To avoid Ihis probIem, eiIher speciIy Ihe --no-dirs opIion
(iI you don'I need Io expand a direcIory's conIenI), or Iurn on recursion and excIude
Ihe conIenI oI subdirecIories: -r --exclude='j*j*'.
--bwlimit=KBPS
This opIion aIIows you Io speciIy a maximum IransIer raIe in kiIobyIes per second.
This opIion is mosI eIIecIive when using rsync wiIh Iarge IiIes (severaI megabyIes and
up). Due Io Ihe naIure oI rsync IransIers, bIocks oI daIa are senI, Ihen iI rsync
deIermines Ihe IransIer was Ioo IasI, iI wiII waiI beIore sending Ihe nexI daIa bIock.
The resuII is an average IransIer raIe eguaIing Ihe speciIied IimiI. A vaIue oI zero
speciIies no IimiI.
--write-batch=FILL
Record a IiIe IhaI can IaIer be appIied Io anoIher idenIicaI desIinaIion wiIh --read-
batch. See Ihe "8ATCH MOD" secIion Ior deIaiIs, and aIso Ihe --only-write-batch
opIion.
--only-write-batch=FILL
Works Iike --write-batch, excepI IhaI no updaIes are made on Ihe desIinaIion sysIem
when creaIing Ihe baIch. This IeIs you IransporI Ihe changes Io Ihe desIinaIion sysIem
via some oIher means and Ihen appIy Ihe changes via --read-batch.
NoIe IhaI you can IeeI Iree Io wriIe Ihe baIch direcIIy Io some porIabIe media: iI Ihis
media IiIIs Io capaciIy beIore Ihe end oI Ihe IransIer, you can |usI appIy IhaI parIiaI
IransIer Io Ihe desIinaIion and repeaI Ihe whoIe process Io geI Ihe resI oI Ihe changes
(as Iong as you don'I mind a parIiaIIy updaIed desIinaIion sysIem whiIe Ihe muIIi-
updaIe cycIe is happening).
AIso noIe IhaI you onIy save bandwidIh when pushing changes Io a remoIe sysIem
because Ihis aIIows Ihe baIched daIa Io be diverIed Irom Ihe sender inIo Ihe baIch IiIe
wiIhouI having Io IIow over Ihe wire Io Ihe receiver (when puIIing, Ihe sender is
remoIe, and Ihus can'I wriIe Ihe baIch).
--read-batch=FILL
AppIy aII oI Ihe changes sIored in !L, a IiIe previousIy generaIed by --write-batch. !I
F|L is -, Ihe baIch daIa wiII be read Irom sIandard inpuI. See Ihe "8ATCH MOD"
secIion Ior deIaiIs.
--protocol=NUM
orce an oIder proIocoI version Io be used. This is useIuI Ior creaIing a baIch IiIe IhaI is
compaIibIe wiIh an oIder version oI rsync. or insIance, iI rsync 2.6.4 is being used
wiIh Ihe --write-batch opIion, buI rsync 2.6.3 is whaI wiII be used Io run Ihe
--read-batch opIion, you shouId use "--proIocoI=28" when creaIing Ihe baIch IiIe Io
Iorce Ihe oIder proIocoI version Io be used in Ihe baIch IiIe (assuming you can'I
upgrade Ihe rsync on Ihe reading sysIem).
--iconv=CONVLRT_SPLC
Rsync can converI IiIenames beIween characIer seIs using Ihis opIion. Using a
CONVRT_SPC oI "." IeIIs rsync Io Iook up Ihe deIauII characIer-seI via Ihe IocaIe
seIIing. AIIernaIeIy, you can IuIIy speciIy whaI conversion Io do by giving a IocaI and a
remoIe charseI separaIed by a comma in Ihe order --iconv=LOCAL,RLMOTL, e.g.
--iconv=utf8,iso88591. This order ensures IhaI Ihe opIion wiII sIay Ihe same wheIher
you're pushing or puIIing IiIes. inaIIy, you can speciIy eiIher --no-iconv or a
37 sur SS 23/03/2013 17:4S
CONVRT_SPC oI "-" Io Iurn oII any conversion. The deIauII seIIing oI Ihis opIion is
siIe-speciIic, and can aIso be aIIecIed via Ihe RSYNC_!CONV environmenI variabIe.
or a IisI oI whaI charseI names your IocaI iconv Iibrary supporIs, you can run "iconv
--IisI".
!I you speciIy Ihe --protect-args opIion (-s), rsync wiII IransIaIe Ihe IiIenames you
speciIy on Ihe command-Iine IhaI are being senI Io Ihe remoIe hosI. See aIso Ihe
--files-from opIion.
NoIe IhaI rsync does noI do any conversion oI names in IiIIer IiIes (incIuding
incIude/excIude IiIes). !I is up Io you Io ensure IhaI you're speciIying maIching ruIes
IhaI can maIch on boIh sides oI Ihe IransIer. or insIance, you can speciIy exIra
incIude/excIude ruIes iI Ihere are IiIename diIIerences on Ihe Iwo sides IhaI need Io be
accounIed Ior.
When you pass an --iconv opIion Io an rsync daemon IhaI aIIows iI, Ihe daemon uses
Ihe charseI speciIied in iIs "charseI" conIiguraIion parameIer regardIess oI Ihe remoIe
charseI you acIuaIIy pass. Thus, you may IeeI Iree Io speciIy |usI Ihe IocaI charseI Ior a
daemon IransIer (e.g. --iconv=utf8).
-4, --ipv4 or -6, --ipv6
TeIIs rsync Io preIer !Pv4/!Pv6 when creaIing sockeIs. This onIy aIIecIs sockeIs IhaI
rsync has direcI conIroI over, such as Ihe ouIgoing sockeI when direcIIy conIacIing an
rsync daemon. See aIso Ihese opIions in Ihe --daemon mode secIion.
!I rsync was compIied wiIhouI supporI Ior !Pv6, Ihe --ipv6 opIion wiII have no eIIecI.
The --version ouIpuI wiII IeII you iI Ihis is Ihe case.
--checksum-seed=NUM
SeI Ihe checksum seed Io Ihe inIeger NUM. This 4 byIe checksum seed is incIuded in
each bIock and IiIe checksum caIcuIaIion. 8y deIauII Ihe checksum seed is generaIed
by Ihe server and deIauIIs Io Ihe currenI l1me{} . This opIion is used Io seI a speciIic
checksum seed, which is useIuI Ior appIicaIions IhaI wanI repeaIabIe bIock and IiIe
checksums, or in Ihe case where Ihe user wanIs a more random checksum seed.
SeIIing NUM Io 0 causes rsync Io use Ihe deIauII oI l1me{} Ior checksum seed.
DALMON OPTIONS
The opIions aIIowed when sIarIing an rsync daemon are as IoIIows:
--daemon
This IeIIs rsync IhaI iI is Io run as a daemon. The daemon you sIarI running may be
accessed using an rsync cIienI using Ihe host::module or rsync:jjhostjmodulej synIax.
!I sIandard inpuI is a sockeI Ihen rsync wiII assume IhaI iI is being run via ineId,
oIherwise iI wiII deIach Irom Ihe currenI IerminaI and become a background daemon.
The daemon wiII read Ihe conIig IiIe (rsyncd.conI) on each connecI made by a cIienI
and respond Io reguesIs accordingIy. See Ihe rsyncd.conf(S) man page Ior more
deIaiIs.
--address
8y deIauII rsync wiII bind Io Ihe wiIdcard address when run as a daemon wiIh Ihe
--daemon opIion. The --address opIion aIIows you Io speciIy a speciIic !P address (or
38 sur SS 23/03/2013 17:4S
hosIname) Io bind Io. This makes virIuaI hosIing possibIe in con|uncIion wiIh Ihe
--config opIion. See aIso Ihe "address" gIobaI opIion in Ihe rsyncd.conI manpage.
--bwlimit=KBPS
This opIion aIIows you Io speciIy a maximum IransIer raIe in kiIobyIes per second Ior
Ihe daIa Ihe daemon sends. The cIienI can sIiII speciIy a smaIIer --bwlimit vaIue, buI
Iheir reguesIed vaIue wiII be rounded down iI Ihey Iry Io exceed iI. See Ihe cIienI
version oI Ihis opIion (above) Ior some exIra deIaiIs.
--config=FILL
This speciIies an aIIernaIe conIig IiIe Ihan Ihe deIauII. This is onIy reIevanI when
--daemon is speciIied. The deIauII is /eIc/rsyncd.conI unIess Ihe daemon is running
over a remoIe sheII program and Ihe remoIe user is noI Ihe super-user; in IhaI case Ihe
deIauII is rsyncd.conI in Ihe currenI direcIory (IypicaIIy $HOM).
--no-detach
When running as a daemon, Ihis opIion insIrucIs rsync Io noI deIach iIseII and become
a background process. This opIion is reguired when running as a service on Cygwin,
and may aIso be useIuI when rsync is supervised by a program such as daemontools
or A!X's System Resource Controller. --no-detach is aIso recommended when rsync is
run under a debugger. This opIion has no eIIecI iI rsync is run Irom ineId or sshd.
--port=PORT
This speciIies an aIIernaIe TCP porI number Ior Ihe daemon Io IisIen on raIher Ihan Ihe
deIauII oI 873. See aIso Ihe "porI" gIobaI opIion in Ihe rsyncd.conI manpage.
--log-file=FILL
This opIion IeIIs Ihe rsync daemon Io use Ihe given Iog-IiIe name insIead oI using Ihe
"Iog IiIe" seIIing in Ihe conIig IiIe.
--log-file-format=FORMAT
This opIion IeIIs Ihe rsync daemon Io use Ihe given ORMAT sIring insIead oI using Ihe
"Iog IormaI" seIIing in Ihe conIig IiIe. !I aIso enabIes "IransIer Iogging" unIess Ihe sIring
is empIy, in which case IransIer Iogging is Iurned oII.
--sockopts
This overrides Ihe socket options seIIing in Ihe rsyncd.conI IiIe and has Ihe same
synIax.
-v, --verbose
This opIion increases Ihe amounI oI inIormaIion Ihe daemon Iogs during iIs sIarIup
phase. AIIer Ihe cIienI connecIs, Ihe daemon's verbosiIy IeveI wiII be conIroIIed by Ihe
opIions IhaI Ihe cIienI used and Ihe "max verbosiIy" seIIing in Ihe moduIe's conIig
secIion.
-4, --ipv4 or -6, --ipv6
TeIIs rsync Io preIer !Pv4/!Pv6 when creaIing Ihe incoming sockeIs IhaI Ihe rsync
daemon wiII use Io IisIen Ior connecIions. One oI Ihese opIions may be reguired in
oIder versions oI Linux Io work around an !Pv6 bug in Ihe kerneI (iI you see an
"address aIready in use" error when noIhing eIse is using Ihe porI, Iry speciIying --ipv6
or --ipv4 when sIarIing Ihe daemon).
!I rsync was compIied wiIhouI supporI Ior !Pv6, Ihe --ipv6 opIion wiII have no eIIecI.
The --version ouIpuI wiII IeII you iI Ihis is Ihe case.
-h, --help
When speciIied aIIer --daemon, prinI a shorI heIp page describing Ihe opIions
avaiIabIe Ior sIarIing an rsync daemon.
39 sur SS 23/03/2013 17:4S
FILTLR RULLS
The IiIIer ruIes aIIow Ior IIexibIe seIecIion oI which IiIes Io IransIer (incIude) and which IiIes
Io skip (excIude). The ruIes eiIher direcIIy speciIy incIude/excIude paIIerns or Ihey speciIy a
way Io acguire more incIude/excIude paIIerns (e.g. Io read Ihem Irom a IiIe).
As Ihe IisI oI IiIes/direcIories Io IransIer is buiII, rsync checks each name Io be IransIerred
againsI Ihe IisI oI incIude/excIude paIIerns in Iurn, and Ihe IirsI maIching paIIern is acIed
on: iI iI is an excIude paIIern, Ihen IhaI IiIe is skipped; iI iI is an incIude paIIern Ihen IhaI
IiIename is noI skipped; iI no maIching paIIern is Iound, Ihen Ihe IiIename is noI skipped.
Rsync buiIds an ordered IisI oI IiIIer ruIes as speciIied on Ihe command-Iine. iIIer ruIes
have Ihe IoIIowing synIax:
RuLE |PATTERN_0R_ITLENAME]
RuLE,M00TITERS |PATTERN_0R_ITLENAME]
You have your choice oI using eiIher shorI or Iong RUL names, as described beIow. !I you
use a shorI-named ruIe, Ihe ',' separaIing Ihe RUL Irom Ihe MOD!!RS is opIionaI. The
PATTRN or !LNAM IhaI IoIIows (when presenI) musI come aIIer eiIher a singIe space or
an underscore (_). Here are Ihe avaiIabIe ruIe preIixes:
exclude, - speciIies an excIude paIIern.
include, speciIies an incIude paIIern.
merge, . speciIies a merge-IiIe Io read Ior more ruIes.
dir-merge, : speciIies a per-direcIory merge-IiIe.
hide, H speciIies a paIIern Ior hiding IiIes Irom Ihe IransIer.
show, S IiIes IhaI maIch Ihe paIIern are noI hidden.
protect, P speciIies a paIIern Ior proIecIing IiIes Irom deIeIion.
risk, R IiIes IhaI maIch Ihe paIIern are noI proIecIed.
clear, ! cIears Ihe currenI incIude/excIude IisI (Iakes no arg)
When ruIes are being read Irom a IiIe, empIy Iines are ignored, as are commenI Iines IhaI
sIarI wiIh a "#".
NoIe IhaI Ihe --include/--exclude command-Iine opIions do noI aIIow Ihe IuII range oI ruIe
parsing as described above -- Ihey onIy aIIow Ihe speciIicaIion oI incIude/excIude paIIerns
pIus a "!" Ioken Io cIear Ihe IisI (and Ihe normaI commenI parsing when ruIes are read Irom
a IiIe). !I a paIIern does noI begin wiIh "- " (dash, space) or " " (pIus, space), Ihen Ihe ruIe
wiII be inIerpreIed as iI " " (Ior an incIude opIion) or "- " (Ior an excIude opIion) were
preIixed Io Ihe sIring. A --filter opIion, on Ihe oIher hand, musI aIways conIain eiIher a
shorI or Iong ruIe name aI Ihe sIarI oI Ihe ruIe.
NoIe aIso IhaI Ihe --filter, --include, and --exclude opIions Iake one ruIe/paIIern each. To
add muIIipIe ones, you can repeaI Ihe opIions on Ihe command-Iine, use Ihe merge-IiIe
synIax oI Ihe --filter opIion, or Ihe --include-from/--exclude-from opIions.
40 sur SS 23/03/2013 17:4S
INCLUDLjLXCLUDL PATTLRN RULLS
You can incIude and excIude IiIes by speciIying paIIerns using Ihe "", "-", eIc. IiIIer ruIes (as
inIroduced in Ihe !LTR RULS secIion above). The incIude/excIude ruIes each speciIy a
paIIern IhaI is maIched againsI Ihe names oI Ihe IiIes IhaI are going Io be IransIerred. These
paIIerns can Iake severaI Iorms:
o
iI Ihe paIIern sIarIs wiIh a / Ihen iI is anchored Io a parIicuIar spoI in Ihe hierarchy oI
IiIes, oIherwise iI is maIched againsI Ihe end oI Ihe paIhname. This is simiIar Io a
Ieading ^ in reguIar expressions. Thus "/Ioo" wouId maIch a name oI "Ioo" aI eiIher Ihe
"rooI oI Ihe IransIer" (Ior a gIobaI ruIe) or in Ihe merge-IiIe's direcIory (Ior a
per-direcIory ruIe). An unguaIiIied "Ioo" wouId maIch a name oI "Ioo" anywhere in Ihe
Iree because Ihe aIgoriIhm is appIied recursiveIy Irom Ihe Iop down; iI behaves as iI
each paIh componenI geIs a Iurn aI being Ihe end oI Ihe IiIename. ven Ihe
unanchored "sub/Ioo" wouId maIch aI any poinI in Ihe hierarchy where a "Ioo" was
Iound wiIhin a direcIory named "sub". See Ihe secIion on ANCHOR!NC
!NCLUD/XCLUD PATTRNS Ior a IuII discussion oI how Io speciIy a paIIern IhaI
maIches aI Ihe rooI oI Ihe IransIer.
o
iI Ihe paIIern ends wiIh a / Ihen iI wiII onIy maIch a direcIory, noI a reguIar IiIe,
symIink, or device.
o
rsync chooses beIween doing a simpIe sIring maIch and wiIdcard maIching by
checking iI Ihe paIIern conIains one oI Ihese Ihree wiIdcard characIers: '"', '?', and '[' .
o
a '"' maIches any paIh componenI, buI iI sIops aI sIashes.
o
use '""' Io maIch anyIhing, incIuding sIashes.
o
a '?' maIches any characIer excepI a sIash (/).
o
a '[' inIroduces a characIer cIass, such as [a-z] or [[:aIpha:]].
o
in a wiIdcard paIIern, a backsIash can be used Io escape a wiIdcard characIer, buI iI is
maIched IiIeraIIy when no wiIdcards are presenI.
o
iI Ihe paIIern conIains a / (noI counIing a IraiIing /) or a """", Ihen iI is maIched againsI
Ihe IuII paIhname, incIuding any Ieading direcIories. !I Ihe paIIern doesn'I conIain a /
or a """", Ihen iI is maIched onIy againsI Ihe IinaI componenI oI Ihe IiIename.
(Remember IhaI Ihe aIgoriIhm is appIied recursiveIy so "IuII IiIename" can acIuaIIy be
any porIion oI a paIh Irom Ihe sIarIing direcIory on down.)
o
a IraiIing "dir_name/"""" wiII maIch boIh Ihe direcIory (as iI "dir_name/" had been
speciIied) and everyIhing in Ihe direcIory (as iI "dir_name/""" had been speciIied). This
41 sur SS 23/03/2013 17:4S
behavior was added in version 2.6.7.
NoIe IhaI, when using Ihe --recursive (-r) opIion (which is impIied by -a), every
subcomponenI oI every paIh is visiIed Irom Ihe Iop down, so incIude/excIude paIIerns geI
appIied recursiveIy Io each subcomponenI's IuII name (e.g. Io incIude "/Ioo/bar/baz" Ihe
subcomponenIs "/Ioo" and "/Ioo/bar" musI noI be excIuded). The excIude paIIerns acIuaIIy
shorI-circuiI Ihe direcIory IraversaI sIage when rsync Iinds Ihe IiIes Io send. !I a paIIern
excIudes a parIicuIar parenI direcIory, iI can render a deeper incIude paIIern ineIIecIuaI
because rsync did noI descend Ihrough IhaI excIuded secIion oI Ihe hierarchy. This is
parIicuIarIy imporIanI when using a IraiIing '"' ruIe. or insIance, Ihis won'I work:
+ 1some1palh1lh1s-i1le-W1ll-nol-be-iound
+ 1i1le-1s-1ncluded
- *
This IaiIs because Ihe parenI direcIory "some" is excIuded by Ihe '"' ruIe, so rsync never
visiIs any oI Ihe IiIes in Ihe "some" or "some/paIh" direcIories. One soIuIion is Io ask Ior aII
direcIories in Ihe hierarchy Io be incIuded by using a singIe ruIe: " "/" (puI iI somewhere
beIore Ihe "- "" ruIe), and perhaps use Ihe --prune-empty-dirs opIion. AnoIher soIuIion is Io
add speciIic incIude ruIes Ior aII Ihe parenI dirs IhaI need Io be visiIed. or insIance, Ihis seI
oI ruIes works Iine:
+ 1some1
+ 1some1palh1
+ 1some1palh1lh1s-i1le-1s-iound
+ 1i1le-also-1ncluded
- *
Here are some exampIes oI excIude/incIude maIching:
o
"- ".o" wouId excIude aII names maIching ".o
o
"- /Ioo" wouId excIude a IiIe (or direcIory) named Ioo in Ihe IransIer-rooI direcIory
o
"- Ioo/" wouId excIude any direcIory named Ioo
o
"- /Ioo/"/bar" wouId excIude any IiIe named bar which is aI Iwo IeveIs beIow a direcIory
named Ioo in Ihe IransIer-rooI direcIory
o
"- /Ioo/""/bar" wouId excIude any IiIe named bar Iwo or more IeveIs beIow a direcIory
named Ioo in Ihe IransIer-rooI direcIory
o
The combinaIion oI " "/", " ".c", and "- "" wouId incIude aII direcIories and C source
IiIes buI noIhing eIse (see aIso Ihe --prune-empty-dirs opIion)
o
The combinaIion oI " Ioo/", " Ioo/bar.c", and "- "" wouId incIude onIy Ihe Ioo
direcIory and Ioo/bar.c (Ihe Ioo direcIory musI be expIiciIIy incIuded or iI wouId be
excIuded by Ihe """)
The IoIIowing modiIiers are accepIed aIIer a "" or "-":
42 sur SS 23/03/2013 17:4S
o
A j speciIies IhaI Ihe incIude/excIude ruIe shouId be maIched againsI Ihe absoIuIe
paIhname oI Ihe currenI iIem. or exampIe, "-/ /eIc/passwd" wouId excIude Ihe passwd
IiIe any Iime Ihe IransIer was sending IiIes Irom Ihe "/eIc" direcIory, and "-/ subdir/Ioo"
wouId aIways excIude "Ioo" when iI is in a dir named "subdir", even iI "Ioo" is aI Ihe
rooI oI Ihe currenI IransIer.
o
A ! speciIies IhaI Ihe incIude/excIude shouId Iake eIIecI iI Ihe paIIern IaiIs Io maIch. or
insIance, "-! "/" wouId excIude aII non-direcIories.
o
A C is used Io indicaIe IhaI aII Ihe gIobaI CVS-excIude ruIes shouId be inserIed as
excIudes in pIace oI Ihe "-C". No arg shouId IoIIow.
o
An s is used Io indicaIe IhaI Ihe ruIe appIies Io Ihe sending side. When a ruIe aIIecIs Ihe
sending side, iI prevenIs IiIes Irom being IransIerred. The deIauII is Ior a ruIe Io aIIecI
boIh sides unIess --delete-excluded was speciIied, in which case deIauII ruIes become
sender-side onIy. See aIso Ihe hide (H) and show (S) ruIes, which are an aIIernaIe way
Io speciIy sending-side incIudes/excIudes.
o
An r is used Io indicaIe IhaI Ihe ruIe appIies Io Ihe receiving side. When a ruIe aIIecIs
Ihe receiving side, iI prevenIs IiIes Irom being deIeIed. See Ihe s modiIier Ior more
inIo. See aIso Ihe proIecI (P) and risk (R) ruIes, which are an aIIernaIe way Io speciIy
receiver-side incIudes/excIudes.
o
A p indicaIes IhaI a ruIe is perishabIe, meaning IhaI iI is ignored in direcIories IhaI are
being deIeIed. or insIance, Ihe -C opIion's deIauII ruIes IhaI excIude Ihings Iike "CVS"
and "".o" are marked as perishabIe, and wiII noI prevenI a direcIory IhaI was removed
on Ihe source Irom being deIeIed on Ihe desIinaIion.
MLRGL-FILL FILTLR RULLS
You can merge whoIe IiIes inIo your IiIIer ruIes by speciIying eiIher a merge (.) or a
dir-merge (:) IiIIer ruIe (as inIroduced in Ihe !LTR RULS secIion above).
There are Iwo kinds oI merged IiIes -- singIe-insIance ('.') and per-direcIory (':'). A singIe-
insIance merge IiIe is read one Iime, and iIs ruIes are incorporaIed inIo Ihe IiIIer IisI in Ihe
pIace oI Ihe "." ruIe. or per-direcIory merge IiIes, rsync wiII scan every direcIory IhaI iI
Iraverses Ior Ihe named IiIe, merging iIs conIenIs when Ihe IiIe exisIs inIo Ihe currenI IisI oI
inheriIed ruIes. These per-direcIory ruIe IiIes musI be creaIed on Ihe sending side because iI
is Ihe sending side IhaI is being scanned Ior Ihe avaiIabIe IiIes Io IransIer. These ruIe IiIes
may aIso need Io be IransIerred Io Ihe receiving side iI you wanI Ihem Io aIIecI whaI IiIes
don'I geI deIeIed (see PR-D!RCTORY RULS AND DLT beIow).
Some exampIes:
mere 1elc1rsync1deiaull.rules
43 sur SS 23/03/2013 17:4S
. 1elc1rsync1deiaull.rules
d1r-mere .per-d1r-i1ller
d1r-mere,n- .non-1nher1led-per-d1r-excludes
.n- .non-1nher1led-per-d1r-excludes
The IoIIowing modiIiers are accepIed aIIer a merge or dir-merge ruIe:
o
A - speciIies IhaI Ihe IiIe shouId consisI oI onIy excIude paIIerns, wiIh no oIher
ruIe-parsing excepI Ior in-IiIe commenIs.
o
A speciIies IhaI Ihe IiIe shouId consisI oI onIy incIude paIIerns, wiIh no oIher
ruIe-parsing excepI Ior in-IiIe commenIs.
o
A C is a way Io speciIy IhaI Ihe IiIe shouId be read in a CVS-compaIibIe manner. This
Iurns on 'n', 'w', and '-', buI aIso aIIows Ihe IisI-cIearing Ioken (!) Io be speciIied. !I no
IiIename is provided, ".cvsignore" is assumed.
o
A e wiII excIude Ihe merge-IiIe name Irom Ihe IransIer; e.g. "dir-merge,e .ruIes" is Iike
"dir-merge .ruIes" and "- .ruIes".
o
An n speciIies IhaI Ihe ruIes are noI inheriIed by subdirecIories.
o
A w speciIies IhaI Ihe ruIes are word-spIiI on whiIespace insIead oI Ihe normaI
Iine-spIiIIing. This aIso Iurns oII commenIs. NoIe: Ihe space IhaI separaIes Ihe preIix
Irom Ihe ruIe is IreaIed speciaIIy, so "- Ioo bar" is parsed as Iwo ruIes (assuming IhaI
preIix-parsing wasn'I aIso disabIed).
o
You may aIso speciIy any oI Ihe modiIiers Ior Ihe "" or "-" ruIes (above) in order Io
have Ihe ruIes IhaI are read in Irom Ihe IiIe deIauII Io having IhaI modiIier seI (excepI
Ior Ihe ! modiIier, which wouId noI be useIuI). or insIance, "merge,-/ .excI" wouId
IreaI Ihe conIenIs oI .excI as absoIuIe-paIh excIudes, whiIe "dir-merge,s .IiII" and ":sC"
wouId each make aII Iheir per-direcIory ruIes appIy onIy on Ihe sending side. !I Ihe
merge ruIe speciIies sides Io aIIecI (via Ihe s or r modiIier or boIh), Ihen Ihe ruIes in
Ihe IiIe musI noI speciIy sides (via a modiIier or a ruIe preIix such as hide).
Per-direcIory ruIes are inheriIed in aII subdirecIories oI Ihe direcIory where Ihe merge-IiIe
was Iound unIess Ihe 'n' modiIier was used. ach subdirecIory's ruIes are preIixed Io Ihe
inheriIed per-direcIory ruIes Irom iIs parenIs, which gives Ihe newesI ruIes a higher prioriIy
Ihan Ihe inheriIed ruIes. The enIire seI oI dir-merge ruIes are grouped IogeIher in Ihe spoI
where Ihe merge-IiIe was speciIied, so iI is possibIe Io override dir-merge ruIes via a ruIe
IhaI goI speciIied earIier in Ihe IisI oI gIobaI ruIes. When Ihe IisI-cIearing ruIe ("!") is read
Irom a per-direcIory IiIe, iI onIy cIears Ihe inheriIed ruIes Ior Ihe currenI merge IiIe.
AnoIher way Io prevenI a singIe ruIe Irom a dir-merge IiIe Irom being inheriIed is Io anchor
iI wiIh a Ieading sIash. Anchored ruIes in a per-direcIory merge-IiIe are reIaIive Io Ihe
merge-IiIe's direcIory, so a paIIern "/Ioo" wouId onIy maIch Ihe IiIe "Ioo" in Ihe direcIory
where Ihe dir-merge IiIIer IiIe was Iound.
44 sur SS 23/03/2013 17:4S
Here's an exampIe IiIIer IiIe which you'd speciIy via --filter=". file":
mere 1home1user1.lobal-i1ller
- *.z
d1r-mere .rules
+ *.|ch]
- *.o
This wiII merge Ihe conIenIs oI Ihe /home/user/.gIobaI-IiIIer IiIe aI Ihe sIarI oI Ihe IisI and
aIso Iurns Ihe ".ruIes" IiIename inIo a per-direcIory IiIIer IiIe. AII ruIes read in prior Io Ihe
sIarI oI Ihe direcIory scan IoIIow Ihe gIobaI anchoring ruIes (i.e. a Ieading sIash maIches aI
Ihe rooI oI Ihe IransIer).
!I a per-direcIory merge-IiIe is speciIied wiIh a paIh IhaI is a parenI direcIory oI Ihe IirsI
IransIer direcIory, rsync wiII scan aII Ihe parenI dirs Irom IhaI sIarIing poinI Io Ihe IransIer
direcIory Ior Ihe indicaIed per-direcIory IiIe. or insIance, here is a common IiIIer (see -F):
--i1ller=`. 1.rsync-i1ller`
ThaI ruIe IeIIs rsync Io scan Ior Ihe IiIe .rsync-IiIIer in aII direcIories Irom Ihe rooI down
Ihrough Ihe parenI direcIory oI Ihe IransIer prior Io Ihe sIarI oI Ihe normaI direcIory scan oI
Ihe IiIe in Ihe direcIories IhaI are senI as a parI oI Ihe IransIer. (NoIe: Ior an rsync daemon,
Ihe rooI is aIways Ihe same as Ihe moduIe's "paIh".)
Some exampIes oI Ihis pre-scanning Ior per-direcIory IiIes:
rsync -avI 1src1palh1 1desl1d1r
rsync -av --i1ller=`. ..1..1.rsync-i1ller` 1src1palh1 1desl1d1r
rsync -av --i1ller=`. .rsync-i1ller` 1src1palh1 1desl1d1r
The IirsI Iwo commands above wiII Iook Ior ".rsync-IiIIer" in "/" and "/src" beIore Ihe normaI
scan begins Iooking Ior Ihe IiIe in "/src/paIh" and iIs subdirecIories. The IasI command
avoids Ihe parenI-dir scan and onIy Iooks Ior Ihe ".rsync-IiIIer" IiIes in each direcIory IhaI is
a parI oI Ihe IransIer.
!I you wanI Io incIude Ihe conIenIs oI a ".cvsignore" in your paIIerns, you shouId use Ihe
ruIe ":C", which creaIes a dir-merge oI Ihe .cvsignore IiIe, buI parsed in a CVS-compaIibIe
manner. You can use Ihis Io aIIecI where Ihe --cvs-exclude (-C) opIion's incIusion oI Ihe
per-direcIory .cvsignore IiIe geIs pIaced inIo your ruIes by puIIing Ihe ":C" wherever you Iike
in your IiIIer ruIes. WiIhouI Ihis, rsync wouId add Ihe dir-merge ruIe Ior Ihe .cvsignore IiIe
aI Ihe end oI aII your oIher ruIes (giving iI a Iower prioriIy Ihan your command-Iine ruIes).
or exampIe:
cal <<E0T ] rsync -avC --i1ller=`. -` a1 b
+ ioo.o
.C
- *.old
E0T
rsync -avC --1nclude=ioo.o -i .C --exclude=`*.old` a1 b
8oIh oI Ihe above rsync commands are idenIicaI. ach one wiII merge aII Ihe per-direcIory
.cvsignore ruIes in Ihe middIe oI Ihe IisI raIher Ihan aI Ihe end. This aIIows Iheir dir-speciIic
ruIes Io supersede Ihe ruIes IhaI IoIIow Ihe :C insIead oI being subservienI Io aII your ruIes.
4S sur SS 23/03/2013 17:4S
To aIIecI Ihe oIher CVS excIude ruIes (i.e. Ihe deIauII IisI oI excIusions, Ihe conIenIs oI
$HOM/.cvsignore, and Ihe vaIue oI $CVS!CNOR) you shouId omiI Ihe -C command-Iine
opIion and insIead inserI a "-C" ruIe inIo your IiIIer ruIes; e.g. "--filter=-C".
LIST-CLLARING FILTLR RULL
You can cIear Ihe currenI incIude/excIude IisI by using Ihe "!" IiIIer ruIe (as inIroduced in Ihe
!LTR RULS secIion above). The "currenI" IisI is eiIher Ihe gIobaI IisI oI ruIes (iI Ihe ruIe is
encounIered whiIe parsing Ihe IiIIer opIions) or a seI oI per-direcIory ruIes (which are
inheriIed in Iheir own sub-IisI, so a subdirecIory can use Ihis Io cIear ouI Ihe parenI's ruIes).
ANCHORING INCLUDLjLXCLUDL PATTLRNS
As menIioned earIier, gIobaI incIude/excIude paIIerns are anchored aI Ihe "rooI oI Ihe
IransIer" (as opposed Io per-direcIory paIIerns, which are anchored aI Ihe merge-IiIe's
direcIory). !I you Ihink oI Ihe IransIer as a subIree oI names IhaI are being senI Irom sender
Io receiver, Ihe IransIer-rooI is where Ihe Iree sIarIs Io be dupIicaIed in Ihe desIinaIion
direcIory. This rooI governs where paIIerns IhaI sIarI wiIh a / maIch.
8ecause Ihe maIching is reIaIive Io Ihe IransIer-rooI, changing Ihe IraiIing sIash on a source
paIh or changing your use oI Ihe --relative opIion aIIecIs Ihe paIh you need Io use in your
maIching (in addiIion Io changing how much oI Ihe IiIe Iree is dupIicaIed on Ihe desIinaIion
hosI). The IoIIowing exampIes demonsIraIe Ihis.
LeI's say IhaI we wanI Io maIch Iwo source IiIes, one wiIh an absoIuIe paIh oI "/home/me/Ioo
/bar", and one wiIh a paIh oI "/home/you/bar/baz". Here is how Ihe various command
choices diIIer Ior a 2-source IransIer:
xampIe cmd: rsync -a /home/me /home/you /desI
/- paIIern: /me/Ioo/bar
/- paIIern: /you/bar/baz
TargeI IiIe: /desI/me/Ioo/bar
TargeI IiIe: /desI/you/bar/baz
xampIe cmd: rsync -a /home/me/ /home/you/ /desI
/- paIIern: /Ioo/bar (noIe missing "me")
/- paIIern: /bar/baz (noIe missing "you")
TargeI IiIe: /desI/Ioo/bar
TargeI IiIe: /desI/bar/baz
xampIe cmd: rsync -a --reIaIive /home/me/ /home/you /desI
/- paIIern: /home/me/Ioo/bar (noIe IuII paIh)
/- paIIern: /home/you/bar/baz (diIIo)
TargeI IiIe: /desI/home/me/Ioo/bar
46 sur SS 23/03/2013 17:4S
TargeI IiIe: /desI/home/you/bar/baz
xampIe cmd: cd /home; rsync -a --reIaIive me/Ioo you/ /desI
/- paIIern: /me/Ioo/bar (sIarIs aI speciIied paIh)
/- paIIern: /you/bar/baz (diIIo)
TargeI IiIe: /desI/me/Ioo/bar
TargeI IiIe: /desI/you/bar/baz
The easiesI way Io see whaI name you shouId IiIIer is Io |usI Iook aI Ihe ouIpuI when using
--verbose and puI a / in IronI oI Ihe name (use Ihe --dry-run opIion iI you're noI yeI ready Io
copy any IiIes).
PLR-DIRLCTORY RULLS AND DLLLTL
WiIhouI a deIeIe opIion, per-direcIory ruIes are onIy reIevanI on Ihe sending side, so you
can IeeI Iree Io excIude Ihe merge IiIes IhemseIves wiIhouI aIIecIing Ihe IransIer. To make
Ihis easy, Ihe 'e' modiIier adds Ihis excIude Ior you, as seen in Ihese Iwo eguivaIenI
commands:
rsync -av --i1ller=`. .excl` --exclude=.excl hosl.src1d1r 1desl
rsync -av --i1ller=`.e .excl` hosl.src1d1r 1desl
However, iI you wanI Io do a deIeIe on Ihe receiving side AND you wanI some IiIes Io be
excIuded Irom being deIeIed, you'II need Io be sure IhaI Ihe receiving side knows whaI IiIes
Io excIude. The easiesI way is Io incIude Ihe per-direcIory merge IiIes in Ihe IransIer and use
--delete-after, because Ihis ensures IhaI Ihe receiving side geIs aII Ihe same excIude ruIes as
Ihe sending side beIore iI Iries Io deIeIe anyIhing:
rsync -avI --delele-ailer hosl.src1d1r 1desl
However, iI Ihe merge IiIes are noI a parI oI Ihe IransIer, you'II need Io eiIher speciIy some
gIobaI excIude ruIes (i.e. speciIied on Ihe command Iine), or you'II need Io mainIain your
own per-direcIory merge IiIes on Ihe receiving side. An exampIe oI Ihe IirsI is Ihis (assume
IhaI Ihe remoIe .ruIes IiIes excIude IhemseIves):
rsync -av --i1ller=`. .rules` --i1ller=`. 1my1exlra.rules`
--delele hosl.src1d1r 1desl
!n Ihe above exampIe Ihe exIra.ruIes IiIe can aIIecI boIh sides oI Ihe IransIer, buI (on Ihe
sending side) Ihe ruIes are subservienI Io Ihe ruIes merged Irom Ihe .ruIes IiIes because Ihey
were speciIied aIIer Ihe per-direcIory merge ruIe.
!n one IinaI exampIe, Ihe remoIe side is excIuding Ihe .rsync-IiIIer IiIes Irom Ihe IransIer,
buI we wanI Io use our own .rsync-IiIIer IiIes Io conIroI whaI geIs deIeIed on Ihe receiving
side. To do Ihis we musI speciIicaIIy excIude Ihe per-direcIory merge IiIes (so IhaI Ihey don'I
geI deIeIed) and Ihen puI ruIes inIo Ihe IocaI IiIes Io conIroI whaI eIse shouId noI geI deIeIed.
Like one oI Ihese commands:
47 sur SS 23/03/2013 17:4S
rsync -av --i1ller=`.e 1.rsync-i1ller` --delele \
hosl.src1d1r 1desl
rsync -avII --delele hosl.src1d1r 1desl
BATCH MODL
8aIch mode can be used Io appIy Ihe same seI oI updaIes Io many idenIicaI sysIems.
Suppose one has a Iree which is repIicaIed on a number oI hosIs. Now suppose some
changes have been made Io Ihis source Iree and Ihose changes need Io be propagaIed Io Ihe
oIher hosIs. !n order Io do Ihis using baIch mode, rsync is run wiIh Ihe wriIe-baIch opIion Io
appIy Ihe changes made Io Ihe source Iree Io one oI Ihe desIinaIion Irees. The wriIe-baIch
opIion causes Ihe rsync cIienI Io sIore in a "baIch IiIe" aII Ihe inIormaIion needed Io repeaI
Ihis operaIion againsI oIher, idenIicaI desIinaIion Irees.
CeneraIing Ihe baIch IiIe once saves having Io perIorm Ihe IiIe sIaIus, checksum, and daIa
bIock generaIion more Ihan once when updaIing muIIipIe desIinaIion Irees. MuIIicasI
IransporI proIocoIs can be used Io IransIer Ihe baIch updaIe IiIes in paraIIeI Io many hosIs aI
once, insIead oI sending Ihe same daIa Io every hosI individuaIIy.
To appIy Ihe recorded changes Io anoIher desIinaIion Iree, run rsync wiIh Ihe read-baIch
opIion, speciIying Ihe name oI Ihe same baIch IiIe, and Ihe desIinaIion Iree. Rsync updaIes
Ihe desIinaIion Iree using Ihe inIormaIion sIored in Ihe baIch IiIe.
or your convenience, a scripI IiIe is aIso creaIed when Ihe wriIe-baIch opIion is used: iI wiII
be named Ihe same as Ihe baIch IiIe wiIh ".sh" appended. This scripI IiIe conIains a
command-Iine suiIabIe Ior updaIing a desIinaIion Iree using Ihe associaIed baIch IiIe. !I can
be execuIed using a 8ourne (or 8ourne-Iike) sheII, opIionaIIy passing in an aIIernaIe
desIinaIion Iree paIhname which is Ihen used insIead oI Ihe originaI desIinaIion paIh. This
is useIuI when Ihe desIinaIion Iree paIh on Ihe currenI hosI diIIers Irom Ihe one used Io
creaIe Ihe baIch IiIe.
xampIes:
$ rsync --Wr1le-balch=ioo -a hosl.1source1d1r1 1adesl1d1r1
$ scp ioo* remole.
$ ssh remole .1ioo.sh 1bdesl1d1r1
$ rsync --Wr1le-balch=ioo -a 1source1d1r1 1adesl1d1r1
$ ssh remole rsync --read-balch=- -a 1bdesl1d1r1 <ioo
!n Ihese exampIes, rsync is used Io updaIe /adesI/dir/ Irom /source/dir/ and Ihe inIormaIion
Io repeaI Ihis operaIion is sIored in "Ioo" and "Ioo.sh". The hosI "remoIe" is Ihen updaIed
wiIh Ihe baIched daIa going inIo Ihe direcIory /bdesI/dir. The diIIerences beIween Ihe Iwo
exampIes reveaIs some oI Ihe IIexibiIiIy you have in how you deaI wiIh baIches:
o
The IirsI exampIe shows IhaI Ihe iniIiaI copy doesn'I have Io be IocaI -- you can push or
puII daIa Io/Irom a remoIe hosI using eiIher Ihe remoIe-sheII synIax or rsync daemon
48 sur SS 23/03/2013 17:4S
synIax, as desired.
o
The IirsI exampIe uses Ihe creaIed "Ioo.sh" IiIe Io geI Ihe righI rsync opIions when
running Ihe read-baIch command on Ihe remoIe hosI.
o
The second exampIe reads Ihe baIch daIa via sIandard inpuI so IhaI Ihe baIch IiIe
doesn'I need Io be copied Io Ihe remoIe machine IirsI. This exampIe avoids Ihe Ioo.sh
scripI because iI needed Io use a modiIied --read-batch opIion, buI you couId ediI Ihe
scripI IiIe iI you wished Io make use oI iI (|usI be sure IhaI no oIher opIion is Irying Io
use sIandard inpuI, such as Ihe "--exclude-from=-" opIion).
CaveaIs:
The read-baIch opIion expecIs Ihe desIinaIion Iree IhaI iI is updaIing Io be idenIicaI Io Ihe
desIinaIion Iree IhaI was used Io creaIe Ihe baIch updaIe IiIeseI. When a diIIerence beIween
Ihe desIinaIion Irees is encounIered Ihe updaIe mighI be discarded wiIh a warning (iI Ihe
IiIe appears Io be up-Io-daIe aIready) or Ihe IiIe-updaIe may be aIIempIed and Ihen, iI Ihe
IiIe IaiIs Io veriIy, Ihe updaIe discarded wiIh an error. This means IhaI iI shouId be saIe Io
re-run a read-baIch operaIion iI Ihe command goI inIerrupIed. !I you wish Io Iorce Ihe
baIched-updaIe Io aIways be aIIempIed regardIess oI Ihe IiIe's size and daIe, use Ihe -I
opIion (when reading Ihe baIch). !I an error occurs, Ihe desIinaIion Iree wiII probabIy be in
a parIiaIIy updaIed sIaIe. !n IhaI case, rsync can be used in iIs reguIar (non-baIch) mode oI
operaIion Io Iix up Ihe desIinaIion Iree.
The rsync version used on aII desIinaIions musI be aI IeasI as new as Ihe one used Io
generaIe Ihe baIch IiIe. Rsync wiII die wiIh an error iI Ihe proIocoI version in Ihe baIch IiIe
is Ioo new Ior Ihe baIch-reading rsync Io handIe. See aIso Ihe --protocol opIion Ior a way Io
have Ihe creaIing rsync generaIe a baIch IiIe IhaI an oIder rsync can undersIand. (NoIe IhaI
baIch IiIes changed IormaI in version 2.6.3, so mixing versions oIder Ihan IhaI wiIh newer
versions wiII noI work.)
When reading a baIch IiIe, rsync wiII Iorce Ihe vaIue oI cerIain opIions Io maIch Ihe daIa in
Ihe baIch IiIe iI you didn'I seI Ihem Io Ihe same as Ihe baIch-wriIing command. OIher
opIions can (and shouId) be changed. or insIance --write-batch changes Io --read-batch,
--files-from is dropped, and Ihe --filter/--include/--exclude opIions are noI needed unIess
one oI Ihe --delete opIions is speciIied.
The code IhaI creaIes Ihe 8ATCH.sh IiIe IransIorms any IiIIer/incIude/excIude opIions inIo a
singIe IisI IhaI is appended as a "here" documenI Io Ihe sheII scripI IiIe. An advanced user
can use Ihis Io modiIy Ihe excIude IisI iI a change in whaI geIs deIeIed by --delete is desired.
A normaI user can ignore Ihis deIaiI and |usI use Ihe sheII scripI as an easy way Io run Ihe
appropriaIe --read-batch command Ior Ihe baIched daIa.
The originaI baIch mode in rsync was based on "rsync", buI Ihe IaIesI version uses a new
impIemenIaIion.
49 sur SS 23/03/2013 17:4S
SYMBOLIC LINKS
Three basic behaviors are possibIe when rsync encounIers a symboIic Iink in Ihe source
direcIory.
8y deIauII, symboIic Iinks are noI IransIerred aI aII. A message "skipping non-reguIar" IiIe is
emiIIed Ior any symIinks IhaI exisI.
!I --links is speciIied, Ihen symIinks are recreaIed wiIh Ihe same IargeI on Ihe desIinaIion.
NoIe IhaI --archive impIies --links.
!I --copy-links is speciIied, Ihen symIinks are "coIIapsed" by copying Iheir reIerenI, raIher
Ihan Ihe symIink.
Rsync can aIso disIinguish "saIe" and "unsaIe" symboIic Iinks. An exampIe where Ihis mighI
be used is a web siIe mirror IhaI wishes Io ensure IhaI Ihe rsync moduIe IhaI is copied does
noI incIude symboIic Iinks Io jetcjpasswd in Ihe pubIic secIion oI Ihe siIe. Using --copy-
unsafe-links wiII cause any Iinks Io be copied as Ihe IiIe Ihey poinI Io on Ihe desIinaIion.
Using --safe-links wiII cause unsaIe Iinks Io be omiIIed aIIogeIher. (NoIe IhaI you musI
speciIy --links Ior --safe-links Io have any eIIecI.)
SymboIic Iinks are considered unsaIe iI Ihey are absoIuIe symIinks (sIarI wiIh j), empIy, or iI
Ihey conIain enough ".." componenIs Io ascend Irom Ihe direcIory being copied.
Here's a summary oI how Ihe symIink opIions are inIerpreIed. The IisI is in order oI
precedence, so iI your combinaIion oI opIions isn'I menIioned, use Ihe IirsI Iine IhaI is a
compIeIe subseI oI your opIions:
--copy-links
Turn aII symIinks inIo normaI IiIes (Ieaving no symIinks Ior any oIher opIions Io
aIIecI).
--links --copy-unsafe-links
Turn aII unsaIe symIinks inIo IiIes and dupIicaIe aII saIe symIinks.
--copy-unsafe-links
Turn aII unsaIe symIinks inIo IiIes, noisiIy skip aII saIe symIinks.
--links --safe-links
DupIicaIe saIe symIinks and skip unsaIe ones.
--links
DupIicaIe aII symIinks.
DIAGNOSTICS
rsync occasionaIIy produces error messages IhaI may seem a IiIIIe crypIic. The one IhaI
S0 sur SS 23/03/2013 17:4S
seems Io cause Ihe mosI conIusion is "proIocoI version mismaIch -- is your sheII cIean?".
This message is usuaIIy caused by your sIarIup scripIs or remoIe sheII IaciIiIy producing
unwanIed garbage on Ihe sIream IhaI rsync is using Ior iIs IransporI. The way Io diagnose
Ihis probIem is Io run your remoIe sheII Iike Ihis:
ssh remolehosl 1b1n1lrue > oul.dal
Ihen Iook aI ouI.daI. !I everyIhing is working correcIIy Ihen ouI.daI shouId be a zero IengIh
IiIe. !I you are geIIing Ihe above error Irom rsync Ihen you wiII probabIy Iind IhaI ouI.daI
conIains some IexI or daIa. Look aI Ihe conIenIs and Iry Io work ouI whaI is producing iI.
The mosI common cause is incorrecIIy conIigured sheII sIarIup scripIs (such as .cshrc or
.proIiIe) IhaI conIain ouIpuI sIaIemenIs Ior non-inIeracIive Iogins.
!I you are having IroubIe debugging IiIIer paIIerns, Ihen Iry speciIying Ihe -vv opIion. AI Ihis
IeveI oI verbosiIy rsync wiII show why each individuaI IiIe is incIuded or excIuded.
LXIT VALULS
0
Success
1
SynIax or usage error
2
ProIocoI incompaIibiIiIy
3
rrors seIecIing inpuI/ouIpuI IiIes, dirs
4
ReguesIed acIion noI supporIed: an aIIempI was made Io manipuIaIe 64-biI IiIes on a
pIaIIorm IhaI cannoI supporI Ihem; or an opIion was speciIied IhaI is supporIed by Ihe
cIienI and noI by Ihe server.
5
rror sIarIing cIienI-server proIocoI
6
Daemon unabIe Io append Io Iog-IiIe
10
rror in sockeI !/O
11
rror in IiIe !/O
12
rror in rsync proIocoI daIa sIream
13
rrors wiIh program diagnosIics
14
rror in !PC code
20
S1 sur SS 23/03/2013 17:4S
Received S!CUSR1 or S!C!NT
21
Some error reIurned by Wa1lp1d{}
22
rror aIIocaIing core memory buIIers
23
ParIiaI IransIer due Io error
24
ParIiaI IransIer due Io vanished source IiIes
25
The --max-deIeIe IimiI sIopped deIeIions
30
TimeouI in daIa send/receive
35
TimeouI waiIing Ior daemon connecIion
LNVIRONMLNT VARIABLLS
CVSIGNORL
The CVS!CNOR environmenI variabIe suppIemenIs any ignore paIIerns in .cvsignore
IiIes. See Ihe --cvs-exclude opIion Ior more deIaiIs.
RSYNC_ICONV
SpeciIy a deIauII --iconv seIIing using Ihis environmenI variabIe. (irsI supporIed in
3.0.0.)
RSYNC_RSH
The RSYNC_RSH environmenI variabIe aIIows you Io override Ihe deIauII sheII used as
Ihe IransporI Ior rsync. Command Iine opIions are permiIIed aIIer Ihe command
name, |usI as in Ihe -e opIion.
RSYNC_PROXY
The RSYNC_PROXY environmenI variabIe aIIows you Io redirecI your rsync cIienI Io
use a web proxy when connecIing Io a rsync daemon. You shouId seI RSYNC_PROXY Io
a hosIname:porI pair.
RSYNC_PASSWORD
SeIIing RSYNC_PASSWORD Io Ihe reguired password aIIows you Io run auIhenIicaIed
rsync connecIions Io an rsync daemon wiIhouI user inIervenIion. NoIe IhaI Ihis does
noI suppIy a password Io a remoIe sheII IransporI such as ssh; Io Iearn how Io do IhaI,
consuII Ihe remoIe sheII's documenIaIion.
USLR or LOGNAML
The USR or LOCNAM environmenI variabIes are used Io deIermine Ihe deIauII
username senI Io an rsync daemon. !I neiIher is seI, Ihe username deIauIIs Io
"nobody".
HOML
The HOM environmenI variabIe is used Io Iind Ihe user's deIauII .cvsignore IiIe.
S2 sur SS 23/03/2013 17:4S
FILLS
/eIc/rsyncd.conI or rsyncd.conI
SLL ALSO
rsyncd.conf(S)
BUGS
Iimes are IransIerred as "nix Iime_I vaIues
When IransIerring Io AT IiIesysIems rsync may re-sync unmodiIied IiIes. See Ihe commenIs
on Ihe --modify-window opIion.
IiIe permissions, devices, eIc. are IransIerred as naIive numericaI vaIues
see aIso Ihe commenIs on Ihe --delete opIion
PIease reporI bugs! See Ihe web siIe aI hIIp://rsync.samba.org/
VLRSION
This man page is currenI Ior version 3.0.9 oI rsync.
INTLRNAL OPTIONS
The opIions --server and --sender are used inIernaIIy by rsync, and shouId never be Iyped
by a user under normaI circumsIances. Some awareness oI Ihese opIions may be needed in
cerIain scenarios, such as when seIIing up a Iogin IhaI can onIy run an rsync command. or
insIance, Ihe supporI direcIory oI Ihe rsync disIribuIion has an exampIe scripI named
rrsync (Ior resIricIed rsync) IhaI can be used wiIh a resIricIed ssh Iogin.
CRLDITS
rsync is disIribuIed under Ihe CNU pubIic Iicense. See Ihe IiIe COPY!NC Ior deIaiIs.
S3 sur SS 23/03/2013 17:4S
A W8 siIe is avaiIabIe aI hIIp://rsync.samba.org/. The siIe incIudes an A-O-MaIic which
may cover guesIions unanswered by Ihis manuaI page.
The primary IIp siIe Ior rsync is IIp://rsync.samba.org/pub/rsync.
We wouId be deIighIed Io hear Irom you iI you Iike Ihis program. PIease conIacI Ihe
maiIing-IisI aI rsync@IisIs.samba.org.
This program uses Ihe exceIIenI zIib compression Iibrary wriIIen by ]ean-Ioup CaiIIy and
Mark AdIer.
THANKS
SpeciaI Ihanks go ouI Io: ]ohn Van ssen, MaII McCuIchen, WesIey W. TerpsIra, David
DyksIra, ]os 8ackus, SebasIian Krahmer, MarIin PooI, and our gone-buI-noI-IorgoIIen
compadre, ].W. SchuIIz.
Thanks aIso Io Richard 8renI, 8rendan Mackay, 8iII WaiIe, SIephen RoIhweII and David 8eII.
!'ve probabIy missed some peopIe, my apoIogies iI ! have.
AUTHOR
rsync was originaIIy wriIIen by Andrew TridgeII and PauI Mackerras. Many peopIe have
IaIer conIribuIed Io iI. !I is currenIIy mainIained by Wayne Davison.
MaiIing IisIs Ior supporI and deveIopmenI are avaiIabIe aI hIIp://IisIs.samba.org
Index
NAM
SYNOPS!S
DSCR!PT!ON
CNRAL
STUP
USAC
ADVANCD USAC
CONNCT!NC TO AN RSYNC DAMON
US!NC RSYNC-DAMON ATURS V!A A RMOT-SHLL CONNCT!ON
START!NC AN RSYNC DAMON TO ACCPT CONNCT!ONS
SORTD TRANSR ORDR
XAMPLS
S4 sur SS 23/03/2013 17:4S
OPT!ONS SUMMARY
OPT!ONS
DAMON OPT!ONS
!LTR RULS
!NCLUD/XCLUD PATTRN RULS
MRC-!L !LTR RULS
L!ST-CLAR!NC !LTR RUL
ANCHOR!NC !NCLUD/XCLUD PATTRNS
PR-D!RCTORY RULS AND DLT
8ATCH MOD
SYM8OL!C L!NKS
D!ACNOST!CS
X!T VALUS
NV!RONMNT VAR!A8LS
!LS
S ALSO
8UCS
VRS!ON
!NTRNAL OPT!ONS
CRD!TS
THANKS
AUTHOR
This documenI was creaIed by man2hImI, using Ihe manuaI pages.
Time: 16:43:41 CMT, March 23, 2013
SS sur SS 23/03/2013 17:4S

Man Page of Rsync

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Man Page of Rsync

Uploaded by

Copyright:

Available Formats

ConIenI-Iype: IexI/hImI

You might also like