forked from rclone/rclone
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathMANUAL.html
4276 lines (4265 loc) · 250 KB
/
MANUAL.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta name="generator" content="pandoc" />
<meta name="author" content="Nick Craig-Wood" />
<title>rclone(1) User Manual</title>
<style type="text/css">code{white-space: pre;}</style>
</head>
<body>
<div id="header">
<h1 class="title">rclone(1) User Manual</h1>
<h2 class="author">Nick Craig-Wood</h2>
<h3 class="date">Mar 18, 2017</h3>
</div>
<h1 id="rclone">Rclone</h1>
<p><a href="http://rclone.org/"><img src="http://rclone.org/img/rclone-120x120.png" alt="Logo" /></a></p>
<p>Rclone is a command line program to sync files and directories to and from</p>
<ul>
<li>Google Drive</li>
<li>Amazon S3</li>
<li>Openstack Swift / Rackspace cloud files / Memset Memstore</li>
<li>Dropbox</li>
<li>Google Cloud Storage</li>
<li>Amazon Drive</li>
<li>Microsoft One Drive</li>
<li>Hubic</li>
<li>Backblaze B2</li>
<li>Yandex Disk</li>
<li>SFTP</li>
<li>The local filesystem</li>
</ul>
<p>Features</p>
<ul>
<li>MD5/SHA1 hashes checked at all times for file integrity</li>
<li>Timestamps preserved on files</li>
<li>Partial syncs supported on a whole file basis</li>
<li><a href="http://rclone.org/commands/rclone_copy/">Copy</a> mode to just copy new/changed files</li>
<li><a href="http://rclone.org/commands/rclone_sync/">Sync</a> (one way) mode to make a directory identical</li>
<li><a href="http://rclone.org/commands/rclone_check/">Check</a> mode to check for file hash equality</li>
<li>Can sync to and from network, eg two different cloud accounts</li>
<li>Optional encryption (<a href="http://rclone.org/crypt/">Crypt</a>)</li>
<li>Optional FUSE mount (<a href="http://rclone.org/commands/rclone_mount/">rclone mount</a>)</li>
</ul>
<p>Links</p>
<ul>
<li><a href="http://rclone.org/">Home page</a></li>
<li><a href="http://github.com/ncw/rclone">Github project page for source and bug tracker</a></li>
<li><a href="https://forum.rclone.org">Rclone Forum</a></li>
<li><a href="https://google.com/+RcloneOrg" rel="publisher">Google+ page</a></li>
<li><a href="http://rclone.org/downloads/">Downloads</a></li>
</ul>
<h1 id="install">Install</h1>
<p>Rclone is a Go program and comes as a single binary file.</p>
<h2 id="quickstart">Quickstart</h2>
<ul>
<li><a href="http://rclone.org/downloads/">Download</a> the relevant binary.</li>
<li>Unpack and the <code>rclone</code> binary.</li>
<li>Run <code>rclone config</code> to setup. See <a href="http://rclone.org/docs/">rclone config docs</a> for more details.</li>
</ul>
<p>See below for some expanded Linux / macOS instructions.</p>
<p>See the <a href="http://rclone.org/docs/">Usage section</a> of the docs for how to use rclone, or run <code>rclone -h</code>.</p>
<h2 id="linux-installation-from-precompiled-binary">Linux installation from precompiled binary</h2>
<p>Fetch and unpack</p>
<pre><code>curl -O http://downloads.rclone.org/rclone-current-linux-amd64.zip
unzip rclone-current-linux-amd64.zip
cd rclone-*-linux-amd64</code></pre>
<p>Copy binary file</p>
<pre><code>sudo cp rclone /usr/bin/
sudo chown root:root /usr/bin/rclone
sudo chmod 755 /usr/bin/rclone</code></pre>
<p>Install manpage</p>
<pre><code>sudo mkdir -p /usr/local/share/man/man1
sudo cp rclone.1 /usr/local/share/man/man1/
sudo mandb </code></pre>
<p>Run <code>rclone config</code> to setup. See <a href="http://rclone.org/docs/">rclone config docs</a> for more details.</p>
<pre><code>rclone config</code></pre>
<h2 id="macos-installation-from-precompiled-binary">macOS installation from precompiled binary</h2>
<p>Download the latest version of rclone.</p>
<pre><code>cd && curl -O http://downloads.rclone.org/rclone-current-osx-amd64.zip</code></pre>
<p>Unzip the download and cd to the extracted folder.</p>
<pre><code>unzip -a rclone-current-osx-amd64.zip && cd rclone-*-osx-amd64</code></pre>
<p>Move rclone to your $PATH. You will be prompted for your password.</p>
<pre><code>sudo mv rclone /usr/local/bin/</code></pre>
<p>Remove the leftover files.</p>
<pre><code>cd .. && rm -rf rclone-*-osx-amd64 rclone-current-osx-amd64.zip</code></pre>
<p>Run <code>rclone config</code> to setup. See <a href="http://rclone.org/docs/">rclone config docs</a> for more details.</p>
<pre><code>rclone config</code></pre>
<h2 id="install-from-source">Install from source</h2>
<p>Make sure you have at least <a href="https://golang.org/">Go</a> 1.5 installed. Make sure your <code>GOPATH</code> is set, then:</p>
<pre><code>go get -u -v github.com/ncw/rclone</code></pre>
<p>and this will build the binary in <code>$GOPATH/bin</code>. If you have built rclone before then you will want to update its dependencies first with this</p>
<pre><code>go get -u -v github.com/ncw/rclone/...</code></pre>
<h2 id="installation-with-ansible">Installation with Ansible</h2>
<p>This can be done with <a href="https://github.com/stefangweichinger/ansible-rclone">Stefan Weichinger's ansible role</a>.</p>
<p>Instructions</p>
<ol style="list-style-type: decimal">
<li><code>git clone https://github.com/stefangweichinger/ansible-rclone.git</code> into your local roles-directory</li>
<li>add the role to the hosts you want rclone installed to:</li>
</ol>
<pre><code> - hosts: rclone-hosts
roles:
- rclone</code></pre>
<h2 id="installation-with-snap">Installation with snap</h2>
<h3 id="quickstart-1">Quickstart</h3>
<ul>
<li>install Snapd on your distro using the instructions below</li>
<li>sudo snap install rclone --classic</li>
<li>Run <code>rclone config</code> to setup. See <a href="http://rclone.org/docs/">rclone config docs</a> for more details.</li>
</ul>
<p>See below for how to install snapd if it isn't already installed</p>
<h4 id="arch">Arch</h4>
<pre><code>sudo pacman -S snapd</code></pre>
<p>enable the snapd systemd service:</p>
<pre><code>sudo systemctl enable --now snapd.socket</code></pre>
<h4 id="debian-ubuntu">Debian / Ubuntu</h4>
<pre><code>sudo apt install snapd</code></pre>
<h4 id="fedora">Fedora</h4>
<pre><code>sudo dnf copr enable zyga/snapcore
sudo dnf install snapd</code></pre>
<p>enable the snapd systemd service:</p>
<pre><code>sudo systemctl enable --now snapd.service</code></pre>
<p>SELinux support is in beta, so currently:</p>
<pre><code>sudo setenforce 0</code></pre>
<p>to persist, edit <code>/etc/selinux/config</code> to set <code>SELINUX=permissive</code> and reboot.</p>
<h4 id="gentoo">Gentoo</h4>
<p>Install the <a href="https://github.com/zyga/gentoo-snappy">gentoo-snappy overlay</a>.</p>
<h4 id="openembeddedyocto">OpenEmbedded/Yocto</h4>
<p>Install the <a href="https://github.com/morphis/meta-snappy/blob/master/README.md">snap meta layer</a>.</p>
<h4 id="opensuse">openSUSE</h4>
<pre><code>sudo zypper addrepo http://download.opensuse.org/repositories/system:/snappy/openSUSE_Leap_42.2/ snappy
sudo zypper install snapd</code></pre>
<h4 id="openwrt">OpenWrt</h4>
<p>Enable the snap-openwrt feed.</p>
<h2 id="configure">Configure</h2>
<p>First you'll need to configure rclone. As the object storage systems have quite complicated authentication these are kept in a config file. (See the <code>--config</code> entry for how to find the config file and choose its location.)</p>
<p>The easiest way to make the config is to run rclone with the config option:</p>
<pre><code>rclone config</code></pre>
<p>See the following for detailed instructions for</p>
<ul>
<li><a href="http://rclone.org/drive/">Google drive</a></li>
<li><a href="http://rclone.org/s3/">Amazon S3</a></li>
<li><a href="http://rclone.org/swift/">Swift / Rackspace Cloudfiles / Memset Memstore</a></li>
<li><a href="http://rclone.org/dropbox/">Dropbox</a></li>
<li><a href="http://rclone.org/googlecloudstorage/">Google Cloud Storage</a></li>
<li><a href="http://rclone.org/local/">Local filesystem</a></li>
<li><a href="http://rclone.org/amazonclouddrive/">Amazon Drive</a></li>
<li><a href="http://rclone.org/b2/">Backblaze B2</a></li>
<li><a href="http://rclone.org/hubic/">Hubic</a></li>
<li><a href="http://rclone.org/onedrive/">Microsoft One Drive</a></li>
<li><a href="http://rclone.org/yandex/">Yandex Disk</a></li>
<li><a href="http://rclone.org/sftp/">SFTP</a></li>
<li><a href="http://rclone.org/crypt/">Crypt</a> - to encrypt other remotes</li>
</ul>
<h2 id="usage">Usage</h2>
<p>Rclone syncs a directory tree from one storage system to another.</p>
<p>Its syntax is like this</p>
<pre><code>Syntax: [options] subcommand <parameters> <parameters...></code></pre>
<p>Source and destination paths are specified by the name you gave the storage system in the config file then the sub path, eg "drive:myfolder" to look at "myfolder" in Google drive.</p>
<p>You can define as many storage paths as you like in the config file.</p>
<h2 id="subcommands">Subcommands</h2>
<p>rclone uses a system of subcommands. For example</p>
<pre><code>rclone ls remote:path # lists a re
rclone copy /local/path remote:path # copies /local/path to the remote
rclone sync /local/path remote:path # syncs /local/path to the remote</code></pre>
<h2 id="rclone-config">rclone config</h2>
<p>Enter an interactive configuration session.</p>
<h3 id="synopsis">Synopsis</h3>
<p>Enter an interactive configuration session.</p>
<pre><code>rclone config</code></pre>
<h2 id="rclone-copy">rclone copy</h2>
<p>Copy files from source to dest, skipping already copied</p>
<h3 id="synopsis-1">Synopsis</h3>
<p>Copy the source to the destination. Doesn't transfer unchanged files, testing by size and modification time or MD5SUM. Doesn't delete files from the destination.</p>
<p>Note that it is always the contents of the directory that is synced, not the directory so when source:path is a directory, it's the contents of source:path that are copied, not the directory name and contents.</p>
<p>If dest:path doesn't exist, it is created and the source:path contents go there.</p>
<p>For example</p>
<pre><code>rclone copy source:sourcepath dest:destpath</code></pre>
<p>Let's say there are two files in sourcepath</p>
<pre><code>sourcepath/one.txt
sourcepath/two.txt</code></pre>
<p>This copies them to</p>
<pre><code>destpath/one.txt
destpath/two.txt</code></pre>
<p>Not to</p>
<pre><code>destpath/sourcepath/one.txt
destpath/sourcepath/two.txt</code></pre>
<p>If you are familiar with <code>rsync</code>, rclone always works as if you had written a trailing / - meaning "copy the contents of this directory". This applies to all commands and whether you are talking about the source or destination.</p>
<p>See the <code>--no-traverse</code> option for controlling whether rclone lists the destination directory or not.</p>
<pre><code>rclone copy source:path dest:path</code></pre>
<h2 id="rclone-sync">rclone sync</h2>
<p>Make source and dest identical, modifying destination only.</p>
<h3 id="synopsis-2">Synopsis</h3>
<p>Sync the source to the destination, changing the destination only. Doesn't transfer unchanged files, testing by size and modification time or MD5SUM. Destination is updated to match source, including deleting files if necessary.</p>
<p><strong>Important</strong>: Since this can cause data loss, test first with the <code>--dry-run</code> flag to see exactly what would be copied and deleted.</p>
<p>Note that files in the destination won't be deleted if there were any errors at any point.</p>
<p>It is always the contents of the directory that is synced, not the directory so when source:path is a directory, it's the contents of source:path that are copied, not the directory name and contents. See extended explanation in the <code>copy</code> command above if unsure.</p>
<p>If dest:path doesn't exist, it is created and the source:path contents go there.</p>
<pre><code>rclone sync source:path dest:path</code></pre>
<h2 id="rclone-move">rclone move</h2>
<p>Move files from source to dest.</p>
<h3 id="synopsis-3">Synopsis</h3>
<p>Moves the contents of the source directory to the destination directory. Rclone will error if the source and destination overlap and the remote does not support a server side directory move operation.</p>
<p>If no filters are in use and if possible this will server side move <code>source:path</code> into <code>dest:path</code>. After this <code>source:path</code> will no longer longer exist.</p>
<p>Otherwise for each file in <code>source:path</code> selected by the filters (if any) this will move it into <code>dest:path</code>. If possible a server side move will be used, otherwise it will copy it (server side if possible) into <code>dest:path</code> then delete the original (if no errors on copy) in <code>source:path</code>.</p>
<p><strong>Important</strong>: Since this can cause data loss, test first with the --dry-run flag.</p>
<pre><code>rclone move source:path dest:path</code></pre>
<h2 id="rclone-delete">rclone delete</h2>
<p>Remove the contents of path.</p>
<h3 id="synopsis-4">Synopsis</h3>
<p>Remove the contents of path. Unlike <code>purge</code> it obeys include/exclude filters so can be used to selectively delete files.</p>
<p>Eg delete all files bigger than 100MBytes</p>
<p>Check what would be deleted first (use either)</p>
<pre><code>rclone --min-size 100M lsl remote:path
rclone --dry-run --min-size 100M delete remote:path</code></pre>
<p>Then delete</p>
<pre><code>rclone --min-size 100M delete remote:path</code></pre>
<p>That reads "delete everything with a minimum size of 100 MB", hence delete all files bigger than 100MBytes.</p>
<pre><code>rclone delete remote:path</code></pre>
<h2 id="rclone-purge">rclone purge</h2>
<p>Remove the path and all of its contents.</p>
<h3 id="synopsis-5">Synopsis</h3>
<p>Remove the path and all of its contents. Note that this does not obey include/exclude filters - everything will be removed. Use <code>delete</code> if you want to selectively delete files.</p>
<pre><code>rclone purge remote:path</code></pre>
<h2 id="rclone-mkdir">rclone mkdir</h2>
<p>Make the path if it doesn't already exist.</p>
<h3 id="synopsis-6">Synopsis</h3>
<p>Make the path if it doesn't already exist.</p>
<pre><code>rclone mkdir remote:path</code></pre>
<h2 id="rclone-rmdir">rclone rmdir</h2>
<p>Remove the path if empty.</p>
<h3 id="synopsis-7">Synopsis</h3>
<p>Remove the path. Note that you can't remove a path with objects in it, use purge for that.</p>
<pre><code>rclone rmdir remote:path</code></pre>
<h2 id="rclone-check">rclone check</h2>
<p>Checks the files in the source and destination match.</p>
<h3 id="synopsis-8">Synopsis</h3>
<p>Checks the files in the source and destination match. It compares sizes and hashes (MD5 or SHA1) and logs a report of files which don't match. It doesn't alter the source or destination.</p>
<p>If you supply the --size-only flag, it will only compare the sizes not the hashes as well. Use this for a quick check.</p>
<p>If you supply the --download flag, it will download the data from both remotes and check them against each other on the fly. This can be useful for remotes that don't support hashes or if you really want to check all the data.</p>
<pre><code>rclone check source:path dest:path</code></pre>
<h3 id="options">Options</h3>
<pre><code> --download Check by downloading rather than with hash.</code></pre>
<h2 id="rclone-ls">rclone ls</h2>
<p>List all the objects in the path with size and path.</p>
<h3 id="synopsis-9">Synopsis</h3>
<p>List all the objects in the path with size and path.</p>
<pre><code>rclone ls remote:path</code></pre>
<h2 id="rclone-lsd">rclone lsd</h2>
<p>List all directories/containers/buckets in the path.</p>
<h3 id="synopsis-10">Synopsis</h3>
<p>List all directories/containers/buckets in the path.</p>
<pre><code>rclone lsd remote:path</code></pre>
<h2 id="rclone-lsl">rclone lsl</h2>
<p>List all the objects path with modification time, size and path.</p>
<h3 id="synopsis-11">Synopsis</h3>
<p>List all the objects path with modification time, size and path.</p>
<pre><code>rclone lsl remote:path</code></pre>
<h2 id="rclone-md5sum">rclone md5sum</h2>
<p>Produces an md5sum file for all the objects in the path.</p>
<h3 id="synopsis-12">Synopsis</h3>
<p>Produces an md5sum file for all the objects in the path. This is in the same format as the standard md5sum tool produces.</p>
<pre><code>rclone md5sum remote:path</code></pre>
<h2 id="rclone-sha1sum">rclone sha1sum</h2>
<p>Produces an sha1sum file for all the objects in the path.</p>
<h3 id="synopsis-13">Synopsis</h3>
<p>Produces an sha1sum file for all the objects in the path. This is in the same format as the standard sha1sum tool produces.</p>
<pre><code>rclone sha1sum remote:path</code></pre>
<h2 id="rclone-size">rclone size</h2>
<p>Prints the total size and number of objects in remote:path.</p>
<h3 id="synopsis-14">Synopsis</h3>
<p>Prints the total size and number of objects in remote:path.</p>
<pre><code>rclone size remote:path</code></pre>
<h2 id="rclone-version">rclone version</h2>
<p>Show the version number.</p>
<h3 id="synopsis-15">Synopsis</h3>
<p>Show the version number.</p>
<pre><code>rclone version</code></pre>
<h2 id="rclone-cleanup">rclone cleanup</h2>
<p>Clean up the remote if possible</p>
<h3 id="synopsis-16">Synopsis</h3>
<p>Clean up the remote if possible. Empty the trash or delete old file versions. Not supported by all remotes.</p>
<pre><code>rclone cleanup remote:path</code></pre>
<h2 id="rclone-dedupe">rclone dedupe</h2>
<p>Interactively find duplicate files delete/rename them.</p>
<h3 id="synopsis-17">Synopsis</h3>
<p>By default <code>dedup</code> interactively finds duplicate files and offers to delete all but one or rename them to be different. Only useful with Google Drive which can have duplicate file names.</p>
<p>The <code>dedupe</code> command will delete all but one of any identical (same md5sum) files it finds without confirmation. This means that for most duplicated files the <code>dedupe</code> command will not be interactive. You can use <code>--dry-run</code> to see what would happen without doing anything.</p>
<p>Here is an example run.</p>
<p>Before - with duplicates</p>
<pre><code>$ rclone lsl drive:dupes
6048320 2016-03-05 16:23:16.798000000 one.txt
6048320 2016-03-05 16:23:11.775000000 one.txt
564374 2016-03-05 16:23:06.731000000 one.txt
6048320 2016-03-05 16:18:26.092000000 one.txt
6048320 2016-03-05 16:22:46.185000000 two.txt
1744073 2016-03-05 16:22:38.104000000 two.txt
564374 2016-03-05 16:22:52.118000000 two.txt</code></pre>
<p>Now the <code>dedupe</code> session</p>
<pre><code>$ rclone dedupe drive:dupes
2016/03/05 16:24:37 Google drive root 'dupes': Looking for duplicates using interactive mode.
one.txt: Found 4 duplicates - deleting identical copies
one.txt: Deleting 2/3 identical duplicates (md5sum "1eedaa9fe86fd4b8632e2ac549403b36")
one.txt: 2 duplicates remain
1: 6048320 bytes, 2016-03-05 16:23:16.798000000, md5sum 1eedaa9fe86fd4b8632e2ac549403b36
2: 564374 bytes, 2016-03-05 16:23:06.731000000, md5sum 7594e7dc9fc28f727c42ee3e0749de81
s) Skip and do nothing
k) Keep just one (choose which in next step)
r) Rename all to be different (by changing file.jpg to file-1.jpg)
s/k/r> k
Enter the number of the file to keep> 1
one.txt: Deleted 1 extra copies
two.txt: Found 3 duplicates - deleting identical copies
two.txt: 3 duplicates remain
1: 564374 bytes, 2016-03-05 16:22:52.118000000, md5sum 7594e7dc9fc28f727c42ee3e0749de81
2: 6048320 bytes, 2016-03-05 16:22:46.185000000, md5sum 1eedaa9fe86fd4b8632e2ac549403b36
3: 1744073 bytes, 2016-03-05 16:22:38.104000000, md5sum 851957f7fb6f0bc4ce76be966d336802
s) Skip and do nothing
k) Keep just one (choose which in next step)
r) Rename all to be different (by changing file.jpg to file-1.jpg)
s/k/r> r
two-1.txt: renamed from: two.txt
two-2.txt: renamed from: two.txt
two-3.txt: renamed from: two.txt</code></pre>
<p>The result being</p>
<pre><code>$ rclone lsl drive:dupes
6048320 2016-03-05 16:23:16.798000000 one.txt
564374 2016-03-05 16:22:52.118000000 two-1.txt
6048320 2016-03-05 16:22:46.185000000 two-2.txt
1744073 2016-03-05 16:22:38.104000000 two-3.txt</code></pre>
<p>Dedupe can be run non interactively using the <code>--dedupe-mode</code> flag or by using an extra parameter with the same value</p>
<ul>
<li><code>--dedupe-mode interactive</code> - interactive as above.</li>
<li><code>--dedupe-mode skip</code> - removes identical files then skips anything left.</li>
<li><code>--dedupe-mode first</code> - removes identical files then keeps the first one.</li>
<li><code>--dedupe-mode newest</code> - removes identical files then keeps the newest one.</li>
<li><code>--dedupe-mode oldest</code> - removes identical files then keeps the oldest one.</li>
<li><code>--dedupe-mode rename</code> - removes identical files then renames the rest to be different.</li>
</ul>
<p>For example to rename all the identically named photos in your Google Photos directory, do</p>
<pre><code>rclone dedupe --dedupe-mode rename "drive:Google Photos"</code></pre>
<p>Or</p>
<pre><code>rclone dedupe rename "drive:Google Photos"</code></pre>
<pre><code>rclone dedupe [mode] remote:path</code></pre>
<h3 id="options-1">Options</h3>
<pre><code> --dedupe-mode string Dedupe mode interactive|skip|first|newest|oldest|rename. (default "interactive")</code></pre>
<h2 id="rclone-authorize">rclone authorize</h2>
<p>Remote authorization.</p>
<h3 id="synopsis-18">Synopsis</h3>
<p>Remote authorization. Used to authorize a remote or headless rclone from a machine with a browser - use as instructed by rclone config.</p>
<pre><code>rclone authorize</code></pre>
<h2 id="rclone-cat">rclone cat</h2>
<p>Concatenates any files and sends them to stdout.</p>
<h3 id="synopsis-19">Synopsis</h3>
<p>rclone cat sends any files to standard output.</p>
<p>You can use it like this to output a single file</p>
<pre><code>rclone cat remote:path/to/file</code></pre>
<p>Or like this to output any file in dir or subdirectories.</p>
<pre><code>rclone cat remote:path/to/dir</code></pre>
<p>Or like this to output any .txt files in dir or subdirectories.</p>
<pre><code>rclone --include "*.txt" cat remote:path/to/dir</code></pre>
<p>Use the --head flag to print characters only at the start, --tail for the end and --offset and --count to print a section in the middle. Note that if offset is negative it will count from the end, so --offset -1 --count 1 is equivalent to --tail 1.</p>
<pre><code>rclone cat remote:path</code></pre>
<h3 id="options-2">Options</h3>
<pre><code> --count int Only print N characters. (default -1)
--discard Discard the output instead of printing.
--head int Only print the first N characters.
--offset int Start printing at offset N (or from end if -ve).
--tail int Only print the last N characters.</code></pre>
<h2 id="rclone-copyto">rclone copyto</h2>
<p>Copy files from source to dest, skipping already copied</p>
<h3 id="synopsis-20">Synopsis</h3>
<p>If source:path is a file or directory then it copies it to a file or directory named dest:path.</p>
<p>This can be used to upload single files to other than their current name. If the source is a directory then it acts exactly like the copy command.</p>
<p>So</p>
<pre><code>rclone copyto src dst</code></pre>
<p>where src and dst are rclone paths, either remote:path or /path/to/local or C:.</p>
<p>This will:</p>
<pre><code>if src is file
copy it to dst, overwriting an existing file if it exists
if src is directory
copy it to dst, overwriting existing files if they exist
see copy command for full details</code></pre>
<p>This doesn't transfer unchanged files, testing by size and modification time or MD5SUM. It doesn't delete files from the destination.</p>
<pre><code>rclone copyto source:path dest:path</code></pre>
<h2 id="rclone-cryptcheck">rclone cryptcheck</h2>
<p>Cryptcheck checks the integritity of a crypted remote.</p>
<h3 id="synopsis-21">Synopsis</h3>
<p>rclone cryptcheck checks a remote against a crypted remote. This is the equivalent of running rclone check, but able to check the checksums of the crypted remote.</p>
<p>For it to work the underlying remote of the cryptedremote must support some kind of checksum.</p>
<p>It works by reading the nonce from each file on the cryptedremote: and using that to encrypt each file on the remote:. It then checks the checksum of the underlying file on the cryptedremote: against the checksum of the file it has just encrypted.</p>
<p>Use it like this</p>
<pre><code>rclone cryptcheck /path/to/files encryptedremote:path</code></pre>
<p>You can use it like this also, but that will involve downloading all the files in remote:path.</p>
<pre><code>rclone cryptcheck remote:path encryptedremote:path</code></pre>
<p>After it has run it will log the status of the encryptedremote:.</p>
<pre><code>rclone cryptcheck remote:path cryptedremote:path</code></pre>
<h2 id="rclone-genautocomplete">rclone genautocomplete</h2>
<p>Output bash completion script for rclone.</p>
<h3 id="synopsis-22">Synopsis</h3>
<p>Generates a bash shell autocompletion script for rclone.</p>
<p>This writes to /etc/bash_completion.d/rclone by default so will probably need to be run with sudo or as root, eg</p>
<pre><code>sudo rclone genautocomplete</code></pre>
<p>Logout and login again to use the autocompletion scripts, or source them directly</p>
<pre><code>. /etc/bash_completion</code></pre>
<p>If you supply a command line argument the script will be written there.</p>
<pre><code>rclone genautocomplete [output_file]</code></pre>
<h2 id="rclone-gendocs">rclone gendocs</h2>
<p>Output markdown docs for rclone to the directory supplied.</p>
<h3 id="synopsis-23">Synopsis</h3>
<p>This produces markdown docs for the rclone commands to the directory supplied. These are in a format suitable for hugo to render into the rclone.org website.</p>
<pre><code>rclone gendocs output_directory</code></pre>
<h2 id="rclone-listremotes">rclone listremotes</h2>
<p>List all the remotes in the config file.</p>
<h3 id="synopsis-24">Synopsis</h3>
<p>rclone listremotes lists all the available remotes from the config file.</p>
<p>When uses with the -l flag it lists the types too.</p>
<pre><code>rclone listremotes</code></pre>
<h3 id="options-3">Options</h3>
<pre><code> -l, --long Show the type as well as names.</code></pre>
<h2 id="rclone-mount">rclone mount</h2>
<p>Mount the remote as a mountpoint. <strong>EXPERIMENTAL</strong></p>
<h3 id="synopsis-25">Synopsis</h3>
<p>rclone mount allows Linux, FreeBSD and macOS to mount any of Rclone's cloud storage systems as a file system with FUSE.</p>
<p>This is <strong>EXPERIMENTAL</strong> - use with care.</p>
<p>First set up your remote using <code>rclone config</code>. Check it works with <code>rclone ls</code> etc.</p>
<p>Start the mount like this (note the & on the end to put rclone in the background).</p>
<pre><code>rclone mount remote:path/to/files /path/to/local/mount &</code></pre>
<p>Stop the mount with</p>
<pre><code>fusermount -u /path/to/local/mount</code></pre>
<p>Or if that fails try</p>
<pre><code>fusermount -z -u /path/to/local/mount</code></pre>
<p>Or with OS X</p>
<pre><code>umount /path/to/local/mount</code></pre>
<h3 id="limitations">Limitations</h3>
<p>This can only write files seqentially, it can only seek when reading. This means that many applications won't work with their files on an rclone mount.</p>
<p>The bucket based remotes (eg Swift, S3, Google Compute Storage, B2, Hubic) won't work from the root - you will need to specify a bucket, or a path within the bucket. So <code>swift:</code> won't work whereas <code>swift:bucket</code> will as will <code>swift:bucket/path</code>. None of these support the concept of directories, so empty directories will have a tendency to disappear once they fall out of the directory cache.</p>
<p>Only supported on Linux, FreeBSD and OS X at the moment.</p>
<h3 id="rclone-mount-vs-rclone-synccopy">rclone mount vs rclone sync/copy</h3>
<p>File systems expect things to be 100% reliable, whereas cloud storage systems are a long way from 100% reliable. The rclone sync/copy commands cope with this with lots of retries. However rclone mount can't use retries in the same way without making local copies of the uploads. This might happen in the future, but for the moment rclone mount won't do that, so will be less reliable than the rclone command.</p>
<h3 id="filters">Filters</h3>
<p>Note that all the rclone filters can be used to select a subset of the files to be visible in the mount.</p>
<h3 id="bugs">Bugs</h3>
<ul>
<li>All the remotes should work for read, but some may not for write
<ul>
<li>those which need to know the size in advance won't - eg B2</li>
<li>maybe should pass in size as -1 to mean work it out</li>
<li>Or put in an an upload cache to cache the files on disk first</li>
</ul></li>
</ul>
<h3 id="todo">TODO</h3>
<ul>
<li>Check hashes on upload/download</li>
<li>Preserve timestamps</li>
<li>Move directories</li>
</ul>
<pre><code>rclone mount remote:path /path/to/mountpoint</code></pre>
<h3 id="options-4">Options</h3>
<pre><code> --allow-non-empty Allow mounting over a non-empty directory.
--allow-other Allow access to other users.
--allow-root Allow access to root user.
--debug-fuse Debug the FUSE internals - needs -v.
--default-permissions Makes kernel enforce access control based on the file mode.
--dir-cache-time duration Time to cache directory entries for. (default 5m0s)
--gid uint32 Override the gid field set by the filesystem. (default 502)
--max-read-ahead int The number of bytes that can be prefetched for sequential reads. (default 128k)
--no-modtime Don't read the modification time (can speed things up).
--no-seek Don't allow seeking in files.
--read-only Mount read-only.
--uid uint32 Override the uid field set by the filesystem. (default 502)
--umask int Override the permission bits set by the filesystem. (default 2)
--write-back-cache Makes kernel buffer writes before sending them to rclone. Without this, writethrough caching is used.</code></pre>
<h2 id="rclone-moveto">rclone moveto</h2>
<p>Move file or directory from source to dest.</p>
<h3 id="synopsis-26">Synopsis</h3>
<p>If source:path is a file or directory then it moves it to a file or directory named dest:path.</p>
<p>This can be used to rename files or upload single files to other than their existing name. If the source is a directory then it acts exacty like the move command.</p>
<p>So</p>
<pre><code>rclone moveto src dst</code></pre>
<p>where src and dst are rclone paths, either remote:path or /path/to/local or C:.</p>
<p>This will:</p>
<pre><code>if src is file
move it to dst, overwriting an existing file if it exists
if src is directory
move it to dst, overwriting existing files if they exist
see move command for full details</code></pre>
<p>This doesn't transfer unchanged files, testing by size and modification time or MD5SUM. src will be deleted on successful transfer.</p>
<p><strong>Important</strong>: Since this can cause data loss, test first with the --dry-run flag.</p>
<pre><code>rclone moveto source:path dest:path</code></pre>
<h2 id="rclone-obscure">rclone obscure</h2>
<p>Obscure password for use in the rclone.conf</p>
<h3 id="synopsis-27">Synopsis</h3>
<p>Obscure password for use in the rclone.conf</p>
<pre><code>rclone obscure password</code></pre>
<h2 id="rclone-rmdirs">rclone rmdirs</h2>
<p>Remove any empty directoryies under the path.</p>
<h3 id="synopsis-28">Synopsis</h3>
<p>This removes any empty directories (or directories that only contain empty directories) under the path that it finds, including the path if it has nothing in.</p>
<p>This is useful for tidying up remotes that rclone has left a lot of empty directories in.</p>
<pre><code>rclone rmdirs remote:path</code></pre>
<h2 id="copying-single-files">Copying single files</h2>
<p>rclone normally syncs or copies directories. However if the source remote points to a file, rclone will just copy that file. The destination remote must point to a directory - rclone will give the error <code>Failed to create file system for "remote:file": is a file not a directory</code> if it isn't.</p>
<p>For example, suppose you have a remote with a file in called <code>test.jpg</code>, then you could copy just that file like this</p>
<pre><code>rclone copy remote:test.jpg /tmp/download</code></pre>
<p>The file <code>test.jpg</code> will be placed inside <code>/tmp/download</code>.</p>
<p>This is equivalent to specifying</p>
<pre><code>rclone copy --no-traverse --files-from /tmp/files remote: /tmp/download</code></pre>
<p>Where <code>/tmp/files</code> contains the single line</p>
<pre><code>test.jpg</code></pre>
<p>It is recommended to use <code>copy</code> when copying single files not <code>sync</code>. They have pretty much the same effect but <code>copy</code> will use a lot less memory.</p>
<h2 id="quoting-and-the-shell">Quoting and the shell</h2>
<p>When you are typing commands to your computer you are using something called the command line shell. This interprets various characters in an OS specific way.</p>
<p>Here are some gotchas which may help users unfamiliar with the shell rules</p>
<h3 id="linux-osx">Linux / OSX</h3>
<p>If your names have spaces or shell metacharacters (eg <code>*</code>, <code>?</code>, <code>$</code>, <code>'</code>, <code>"</code> etc) then you must quote them. Use single quotes <code>'</code> by default.</p>
<pre><code>rclone copy 'Important files?' remote:backup</code></pre>
<p>If you want to send a <code>'</code> you will need to use <code>"</code>, eg</p>
<pre><code>rclone copy "O'Reilly Reviews" remote:backup</code></pre>
<p>The rules for quoting metacharacters are complicated and if you want the full details you'll have to consult the manual page for your shell.</p>
<h3 id="windows">Windows</h3>
<p>If your names have spaces in you need to put them in <code>"</code>, eg</p>
<pre><code>rclone copy "E:\folder name\folder name\folder name" remote:backup</code></pre>
<p>If you are using the root directory on its own then don't quote it (see <a href="https://github.com/ncw/rclone/issues/464">#464</a> for why), eg</p>
<pre><code>rclone copy E:\ remote:backup</code></pre>
<h2 id="server-side-copy">Server Side Copy</h2>
<p>Most remotes (but not all - see <a href="/overview/#optional-features">the overview</a>) support server side copy.</p>
<p>This means if you want to copy one folder to another then rclone won't download all the files and re-upload them; it will instruct the server to copy them in place.</p>
<p>Eg</p>
<pre><code>rclone copy s3:oldbucket s3:newbucket</code></pre>
<p>Will copy the contents of <code>oldbucket</code> to <code>newbucket</code> without downloading and re-uploading.</p>
<p>Remotes which don't support server side copy <strong>will</strong> download and re-upload in this case.</p>
<p>Server side copies are used with <code>sync</code> and <code>copy</code> and will be identified in the log when using the <code>-v</code> flag. The may also be used with <code>move</code> if the remote doesn't support server side move.</p>
<p>Server side copies will only be attempted if the remote names are the same.</p>
<p>This can be used when scripting to make aged backups efficiently, eg</p>
<pre><code>rclone sync remote:current-backup remote:previous-backup
rclone sync /path/to/files remote:current-backup</code></pre>
<h2 id="options-5">Options</h2>
<p>Rclone has a number of options to control its behaviour.</p>
<p>Options which use TIME use the go time parser. A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".</p>
<p>Options which use SIZE use kByte by default. However a suffix of <code>b</code> for bytes, <code>k</code> for kBytes, <code>M</code> for MBytes and <code>G</code> for GBytes may be used. These are the binary units, eg 1, 2**10, 2**20, 2**30 respectively.</p>
<h3 id="backup-dirdir">--backup-dir=DIR</h3>
<p>When using <code>sync</code>, <code>copy</code> or <code>move</code> any files which would have been overwritten or deleted are moved in their original hierarchy into this directory.</p>
<p>If <code>--suffix</code> is set, then the moved files will have the suffix added to them. If there is a file with the same path (after the suffix has been added) in DIR, then it will be overwritten.</p>
<p>The remote in use must support server side move or copy and you must use the same remote as the destination of the sync. The backup directory must not overlap the destination directory.</p>
<p>For example</p>
<pre><code>rclone sync /path/to/local remote:current --backup-dir remote:old</code></pre>
<p>will sync <code>/path/to/local</code> to <code>remote:current</code>, but for any files which would have been updated or deleted will be stored in <code>remote:old</code>.</p>
<p>If running rclone from a script you might want to use today's date as the directory name passed to <code>--backup-dir</code> to store the old files, or you might want to pass <code>--suffix</code> with today's date.</p>
<h3 id="bwlimitbandwidth_spec">--bwlimit=BANDWIDTH_SPEC</h3>
<p>This option controls the bandwidth limit. Limits can be specified in two ways: As a single limit, or as a timetable.</p>
<p>Single limits last for the duration of the session. To use a single limit, specify the desired bandwidth in kBytes/s, or use a suffix b|k|M|G. The default is <code>0</code> which means to not limit bandwidth.</p>
<p>For example to limit bandwidth usage to 10 MBytes/s use <code>--bwlimit 10M</code></p>
<p>It is also possible to specify a "timetable" of limits, which will cause certain limits to be applied at certain times. To specify a timetable, format your entries as "HH:MM,BANDWIDTH HH:MM,BANDWITH...".</p>
<p>An example of a typical timetable to avoid link saturation during daytime working hours could be:</p>
<p><code>--bwlimit "08:00,512 12:00,10M 13:00,512 18:00,30M 23:00,off"</code></p>
<p>In this example, the transfer bandwidth will be set to 512kBytes/sec at 8am. At noon, it will raise to 10Mbytes/s, and drop back to 512kBytes/sec at 1pm. At 6pm, the bandwidth limit will be set to 30MBytes/s, and at 11pm it will be completely disabled (full speed). Anything between 11pm and 8am will remain unlimited.</p>
<p>Bandwidth limits only apply to the data transfer. The don't apply to the bandwith of the directory listings etc.</p>
<p>Note that the units are Bytes/s not Bits/s. Typically connections are measured in Bits/s - to convert divide by 8. For example let's say you have a 10 Mbit/s connection and you wish rclone to use half of it - 5 Mbit/s. This is 5/8 = 0.625MByte/s so you would use a <code>--bwlimit 0.625M</code> parameter for rclone.</p>
<h3 id="buffer-sizesize">--buffer-size=SIZE</h3>
<p>Use this sized buffer to speed up file transfers. Each <code>--transfer</code> will use this much memory for buffering.</p>
<p>Set to 0 to disable the buffering for the minimum memory use.</p>
<h3 id="checkersn">--checkers=N</h3>
<p>The number of checkers to run in parallel. Checkers do the equality checking of files during a sync. For some storage systems (eg s3, swift, dropbox) this can take a significant amount of time so they are run in parallel.</p>
<p>The default is to run 8 checkers in parallel.</p>
<h3 id="c---checksum">-c, --checksum</h3>
<p>Normally rclone will look at modification time and size of files to see if they are equal. If you set this flag then rclone will check the file hash and size to determine if files are equal.</p>
<p>This is useful when the remote doesn't support setting modified time and a more accurate sync is desired than just checking the file size.</p>
<p>This is very useful when transferring between remotes which store the same hash type on the object, eg Drive and Swift. For details of which remotes support which hash type see the table in the <a href="http://rclone.org/overview/">overview section</a>.</p>
<p>Eg <code>rclone --checksum sync s3:/bucket swift:/bucket</code> would run much quicker than without the <code>--checksum</code> flag.</p>
<p>When using this flag, rclone won't update mtimes of remote files if they are incorrect as it would normally.</p>
<h3 id="configconfig_file">--config=CONFIG_FILE</h3>
<p>Specify the location of the rclone config file.</p>
<p>Normally the config file is in your home directory as a file called <code>.config/rclone/rclone.conf</code> (or <code>.rclone.conf</code> if created with an older version). If <code>$XDG_CONFIG_HOME</code> is set it will be at <code>$XDG_CONFIG_HOME/rclone/rclone.conf</code></p>
<p>If you run <code>rclone -h</code> and look at the help for the <code>--config</code> option you will see where the default location is for you.</p>
<p>Use this flag to override the config location, eg <code>rclone --config=".myconfig" .config</code>.</p>
<h3 id="contimeouttime">--contimeout=TIME</h3>
<p>Set the connection timeout. This should be in go time format which looks like <code>5s</code> for 5 seconds, <code>10m</code> for 10 minutes, or <code>3h30m</code>.</p>
<p>The connection timeout is the amount of time rclone will wait for a connection to go through to a remote object storage system. It is <code>1m</code> by default.</p>
<h3 id="dedupe-mode-mode">--dedupe-mode MODE</h3>
<p>Mode to run dedupe command in. One of <code>interactive</code>, <code>skip</code>, <code>first</code>, <code>newest</code>, <code>oldest</code>, <code>rename</code>. The default is <code>interactive</code>. See the dedupe command for more information as to what these options mean.</p>
<h3 id="n---dry-run">-n, --dry-run</h3>
<p>Do a trial run with no permanent changes. Use this to see what rclone would do without actually doing it. Useful when setting up the <code>sync</code> command which deletes files in the destination.</p>
<h3 id="ignore-checksum">--ignore-checksum</h3>
<p>Normally rclone will check that the checksums of transferred files match, and give an error "corrupted on transfer" if they don't.</p>
<p>You can use this option to skip that check. You should only use it if you have had the "corrupted on transfer" error message and you are sure you might want to transfer potentially corrupted data.</p>
<h3 id="ignore-existing">--ignore-existing</h3>
<p>Using this option will make rclone unconditionally skip all files that exist on the destination, no matter the content of these files.</p>
<p>While this isn't a generally recommended option, it can be useful in cases where your files change due to encryption. However, it cannot correct partial transfers in case a transfer was interrupted.</p>
<h3 id="ignore-size">--ignore-size</h3>
<p>Normally rclone will look at modification time and size of files to see if they are equal. If you set this flag then rclone will check only the modification time. If <code>--checksum</code> is set then it only checks the checksum.</p>
<p>It will also cause rclone to skip verifying the sizes are the same after transfer.</p>
<p>This can be useful for transferring files to and from onedrive which occasionally misreports the size of image files (see <a href="https://github.com/ncw/rclone/issues/399">#399</a> for more info).</p>
<h3 id="i---ignore-times">-I, --ignore-times</h3>
<p>Using this option will cause rclone to unconditionally upload all files regardless of the state of files on the destination.</p>
<p>Normally rclone would skip any files that have the same modification time and are the same size (or have the same checksum if using <code>--checksum</code>).</p>
<h3 id="log-filefile">--log-file=FILE</h3>
<p>Log all of rclone's output to FILE. This is not active by default. This can be useful for tracking down problems with syncs in combination with the <code>-v</code> flag. See the Logging section for more info.</p>
<h3 id="log-level-level">--log-level LEVEL</h3>
<p>This sets the log level for rclone. The default log level is <code>INFO</code>.</p>
<p><code>DEBUG</code> is equivalent to <code>-vv</code>. It outputs lots of debug info - useful for bug reports and really finding out what rclone is doing.</p>
<p><code>INFO</code> is equivalent to <code>-v</code>. It outputs information about each transfer and prints stats once a minute by default.</p>
<p><code>NOTICE</code> is the default log level if no logging flags are supplied. It outputs very little when things are working normally. It outputs warnings and significant events.</p>
<p><code>ERROR</code> is equivalent to <code>-q</code>. It only output error messages.</p>
<h3 id="low-level-retries-number">--low-level-retries NUMBER</h3>
<p>This controls the number of low level retries rclone does.</p>
<p>A low level retry is used to retry a failing operation - typically one HTTP request. This might be uploading a chunk of a big file for example. You will see low level retries in the log with the <code>-v</code> flag.</p>
<p>This shouldn't need to be changed from the default in normal operations, however if you get a lot of low level retries you may wish to reduce the value so rclone moves on to a high level retry (see the <code>--retries</code> flag) quicker.</p>
<p>Disable low level retries with <code>--low-level-retries 1</code>.</p>
<h3 id="max-depthn">--max-depth=N</h3>
<p>This modifies the recursion depth for all the commands except purge.</p>
<p>So if you do <code>rclone --max-depth 1 ls remote:path</code> you will see only the files in the top level directory. Using <code>--max-depth 2</code> means you will see all the files in first two directory levels and so on.</p>
<p>For historical reasons the <code>lsd</code> command defaults to using a <code>--max-depth</code> of 1 - you can override this with the command line flag.</p>
<p>You can use this command to disable recursion (with <code>--max-depth 1</code>).</p>
<p>Note that if you use this with <code>sync</code> and <code>--delete-excluded</code> the files not recursed through are considered excluded and will be deleted on the destination. Test first with <code>--dry-run</code> if you are not sure what will happen.</p>
<h3 id="modify-windowtime">--modify-window=TIME</h3>
<p>When checking whether a file has been modified, this is the maximum allowed time difference that a file can have and still be considered equivalent.</p>
<p>The default is <code>1ns</code> unless this is overridden by a remote. For example OS X only stores modification times to the nearest second so if you are reading and writing to an OS X filing system this will be <code>1s</code> by default.</p>
<p>This command line flag allows you to override that computed default.</p>
<h3 id="no-gzip-encoding">--no-gzip-encoding</h3>
<p>Don't set <code>Accept-Encoding: gzip</code>. This means that rclone won't ask the server for compressed files automatically. Useful if you've set the server to return files with <code>Content-Encoding: gzip</code> but you uploaded compressed files.</p>
<p>There is no need to set this in normal operation, and doing so will decrease the network transfer efficiency of rclone.</p>
<h3 id="no-update-modtime">--no-update-modtime</h3>
<p>When using this flag, rclone won't update modification times of remote files if they are incorrect as it would normally.</p>
<p>This can be used if the remote is being synced with another tool also (eg the Google Drive client).</p>
<h3 id="q---quiet">-q, --quiet</h3>
<p>Normally rclone outputs stats and a completion message. If you set this flag it will make as little output as possible.</p>
<h3 id="retries-int">--retries int</h3>
<p>Retry the entire sync if it fails this many times it fails (default 3).</p>
<p>Some remotes can be unreliable and a few retries helps pick up the files which didn't get transferred because of errors.</p>
<p>Disable retries with <code>--retries 1</code>.</p>
<h3 id="size-only">--size-only</h3>
<p>Normally rclone will look at modification time and size of files to see if they are equal. If you set this flag then rclone will check only the size.</p>
<p>This can be useful transferring files from dropbox which have been modified by the desktop sync client which doesn't set checksums of modification times in the same way as rclone.</p>
<h3 id="statstime">--stats=TIME</h3>
<p>Commands which transfer data (<code>sync</code>, <code>copy</code>, <code>copyto</code>, <code>move</code>, <code>moveto</code>) will print data transfer stats at regular intervals to show their progress.</p>
<p>This sets the interval.</p>
<p>The default is <code>1m</code>. Use 0 to disable.</p>
<p>If you set the stats interval then all command can show stats. This can be useful when running other commands, <code>check</code> or <code>mount</code> for example.</p>
<h3 id="stats-unitbitsbytes">--stats-unit=bits|bytes</h3>
<p>By default data transfer rates will be printed in bytes/second.</p>
<p>This option allows the data rate to be printed in bits/second.</p>
<p>Data transfer volume will still be reported in bytes.</p>
<p>The rate is reported as a binary unit, not SI unit. So 1 Mbit/s equals 1,048,576 bits/s and not 1,000,000 bits/s.</p>
<p>The default is <code>bytes</code>.</p>
<h3 id="suffixsuffix">--suffix=SUFFIX</h3>
<p>This is for use with <code>--backup-dir</code> only. If this isn't set then <code>--backup-dir</code> will move files with their original name. If it is set then the files will have SUFFIX added on to them.</p>
<p>See <code>--backup-dir</code> for more info.</p>
<h3 id="syslog">--syslog</h3>
<p>On capable OSes (not Windows or Plan9) send all log output to syslog.</p>
<p>This can be useful for running rclone in script or <code>rclone mount</code>.</p>
<h3 id="syslog-facility-string">--syslog-facility string</h3>
<p>If using <code>--syslog</code> this sets the syslog facility (eg <code>KERN</code>, <code>USER</code>). See <code>man syslog</code> for a list of possible facilities. The default facility is <code>DAEMON</code>.</p>
<h3 id="track-renames">--track-renames</h3>
<p>By default rclone doesn't not keep track of renamed files, so if you rename a file locally then sync it to a remote, rclone will delete the old file on the remote and upload a new copy.</p>
<p>If you use this flag, and the remote supports server side copy or server side move, and the source and destination have a compatible hash, then this will track renames during <code>sync</code>, <code>copy</code>, and <code>move</code> operations and perform renaming server-side.</p>
<p>Files will be matched by size and hash - if both match then a rename will be considered.</p>
<p>If the destination does not support server-side copy or move, rclone will fall back to the default behaviour and log an error level message to the console.</p>
<p>Note that <code>--track-renames</code> is incompatible with <code>--no-traverse</code> and that it uses extra memory to keep track of all the rename candidates.</p>
<p>Note also that <code>--track-renames</code> is incompatible with <code>--delete-before</code> and will select <code>--delete-after</code> instead of <code>--delete-during</code>.</p>
<h3 id="delete-beforeduringafter">--delete-(before,during,after)</h3>
<p>This option allows you to specify when files on your destination are deleted when you sync folders.</p>
<p>Specifying the value <code>--delete-before</code> will delete all files present on the destination, but not on the source <em>before</em> starting the transfer of any new or updated files. This uses two passes through the file systems, one for the deletions and one for the copies.</p>
<p>Specifying <code>--delete-during</code> will delete files while checking and uploading files. This is the fastest option and uses the least memory.</p>
<p>Specifying <code>--delete-after</code> (the default value) will delay deletion of files until all new/updated files have been successfully transfered. The files to be deleted are collected in the copy pass then deleted after the copy pass has completed sucessfully. The files to be deleted are held in memory so this mode may use more memory. This is the safest mode as it will only delete files if there have been no errors subsequent to that. If there have been errors before the deletions start then you will get the message <code>not deleting files as there were IO errors</code>.</p>
<h3 id="timeouttime">--timeout=TIME</h3>
<p>This sets the IO idle timeout. If a transfer has started but then becomes idle for this long it is considered broken and disconnected.</p>
<p>The default is <code>5m</code>. Set to 0 to disable.</p>
<h3 id="transfersn">--transfers=N</h3>
<p>The number of file transfers to run in parallel. It can sometimes be useful to set this to a smaller number if the remote is giving a lot of timeouts or bigger if you have lots of bandwidth and a fast remote.</p>
<p>The default is to run 4 file transfers in parallel.</p>
<h3 id="u---update">-u, --update</h3>
<p>This forces rclone to skip any files which exist on the destination and have a modified time that is newer than the source file.</p>
<p>If an existing destination file has a modification time equal (within the computed modify window precision) to the source file's, it will be updated if the sizes are different.</p>
<p>On remotes which don't support mod time directly the time checked will be the uploaded time. This means that if uploading to one of these remoes, rclone will skip any files which exist on the destination and have an uploaded time that is newer than the modification time of the source file.</p>
<p>This can be useful when transferring to a remote which doesn't support mod times directly as it is more accurate than a <code>--size-only</code> check and faster than using <code>--checksum</code>.</p>
<h3 id="v--vv---verbose">-v, -vv, --verbose</h3>
<p>With <code>-v</code> rclone will tell you about each file that is transferred and a small number of significant events.</p>
<p>With <code>-vv</code> rclone will become very verbose telling you about every file it considers and transfers. Please send bug reports with a log with this setting.</p>
<h3 id="v---version">-V, --version</h3>
<p>Prints the version number</p>
<h2 id="configuration-encryption">Configuration Encryption</h2>
<p>Your configuration file contains information for logging in to your cloud services. This means that you should keep your <code>.rclone.conf</code> file in a secure location.</p>
<p>If you are in an environment where that isn't possible, you can add a password to your configuration. This means that you will have to enter the password every time you start rclone.</p>
<p>To add a password to your rclone configuration, execute <code>rclone config</code>.</p>
<pre><code>>rclone config
Current remotes:
e) Edit existing remote
n) New remote
d) Delete remote
s) Set configuration password
q) Quit config
e/n/d/s/q></code></pre>
<p>Go into <code>s</code>, Set configuration password:</p>
<pre><code>e/n/d/s/q> s
Your configuration is not encrypted.
If you add a password, you will protect your login information to cloud services.
a) Add Password
q) Quit to main menu
a/q> a
Enter NEW configuration password:
password:
Confirm NEW password:
password:
Password set
Your configuration is encrypted.
c) Change Password
u) Unencrypt configuration
q) Quit to main menu
c/u/q></code></pre>
<p>Your configuration is now encrypted, and every time you start rclone you will now be asked for the password. In the same menu you can change the password or completely remove encryption from your configuration.</p>
<p>There is no way to recover the configuration if you lose your password.</p>
<p>rclone uses <a href="https://godoc.org/golang.org/x/crypto/nacl/secretbox">nacl secretbox</a> which in turn uses XSalsa20 and Poly1305 to encrypt and authenticate your configuration with secret-key cryptography. The password is SHA-256 hashed, which produces the key for secretbox. The hashed password is not stored.</p>
<p>While this provides very good security, we do not recommend storing your encrypted rclone configuration in public if it contains sensitive information, maybe except if you use a very strong password.</p>
<p>If it is safe in your environment, you can set the <code>RCLONE_CONFIG_PASS</code> environment variable to contain your password, in which case it will be used for decrypting the configuration.</p>
<p>You can set this for a session from a script. For unix like systems save this to a file called <code>set-rclone-password</code>:</p>
<pre><code>#!/bin/echo Source this file don't run it
read -s RCLONE_CONFIG_PASS
export RCLONE_CONFIG_PASS</code></pre>
<p>Then source the file when you want to use it. From the shell you would do <code>source set-rclone-password</code>. It will then ask you for the password and set it in the envonment variable.</p>
<p>If you are running rclone inside a script, you might want to disable password prompts. To do that, pass the parameter <code>--ask-password=false</code> to rclone. This will make rclone fail instead of asking for a password if <code>RCLONE_CONFIG_PASS</code> doesn't contain a valid password.</p>
<h2 id="developer-options">Developer options</h2>
<p>These options are useful when developing or debugging rclone. There are also some more remote specific options which aren't documented here which are used for testing. These start with remote name eg <code>--drive-test-option</code> - see the docs for the remote in question.</p>
<h3 id="cpuprofilefile">--cpuprofile=FILE</h3>
<p>Write CPU profile to file. This can be analysed with <code>go tool pprof</code>.</p>
<h3 id="dump-auth">--dump-auth</h3>
<p>Dump HTTP headers - will contain sensitive info such as <code>Authorization:</code> headers - use <code>--dump-headers</code> to dump without <code>Authorization:</code> headers. Can be very verbose. Useful for debugging only.</p>
<h3 id="dump-bodies">--dump-bodies</h3>
<p>Dump HTTP headers and bodies - may contain sensitive info. Can be very verbose. Useful for debugging only.</p>
<h3 id="dump-filters">--dump-filters</h3>
<p>Dump the filters to the output. Useful to see exactly what include and exclude options are filtering on.</p>
<h3 id="dump-headers">--dump-headers</h3>
<p>Dump HTTP headers with <code>Authorization:</code> lines removed. May still contain sensitive info. Can be very verbose. Useful for debugging only.</p>
<p>Use <code>--dump-auth</code> if you do want the <code>Authorization:</code> headers.</p>
<h3 id="memprofilefile">--memprofile=FILE</h3>
<p>Write memory profile to file. This can be analysed with <code>go tool pprof</code>.</p>
<h3 id="no-check-certificatetruefalse">--no-check-certificate=true/false</h3>
<p><code>--no-check-certificate</code> controls whether a client verifies the server's certificate chain and host name. If <code>--no-check-certificate</code> is true, TLS accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to man-in-the-middle attacks.</p>
<p>This option defaults to <code>false</code>.</p>
<p><strong>This should be used only for testing.</strong></p>
<h3 id="no-traverse">--no-traverse</h3>
<p>The <code>--no-traverse</code> flag controls whether the destination file system is traversed when using the <code>copy</code> or <code>move</code> commands. <code>--no-traverse</code> is not compatible with <code>sync</code> and will be ignored if you supply it with <code>sync</code>.</p>
<p>If you are only copying a small number of files and/or have a large number of files on the destination then <code>--no-traverse</code> will stop rclone listing the destination and save time.</p>
<p>However if you are copying a large number of files, escpecially if you are doing a copy where lots of the files haven't changed and won't need copying then you shouldn't use <code>--no-traverse</code>.</p>
<p>It can also be used to reduce the memory usage of rclone when copying - <code>rclone --no-traverse copy src dst</code> won't load either the source or destination listings into memory so will use the minimum amount of memory.</p>
<h2 id="filtering">Filtering</h2>
<p>For the filtering options</p>
<ul>
<li><code>--delete-excluded</code></li>
<li><code>--filter</code></li>
<li><code>--filter-from</code></li>
<li><code>--exclude</code></li>
<li><code>--exclude-from</code></li>
<li><code>--include</code></li>
<li><code>--include-from</code></li>
<li><code>--files-from</code></li>
<li><code>--min-size</code></li>
<li><code>--max-size</code></li>
<li><code>--min-age</code></li>
<li><code>--max-age</code></li>
<li><code>--dump-filters</code></li>
</ul>
<p>See the <a href="http://rclone.org/filtering/">filtering section</a>.</p>
<h2 id="logging">Logging</h2>
<p>rclone has 4 levels of logging, <code>Error</code>, <code>Notice</code>, <code>Info</code> and <code>Debug</code>.</p>
<p>By default rclone logs to standard error. This means you can redirect standard error and still see the normal output of rclone commands (eg <code>rclone ls</code>).</p>
<p>By default rclone will produce <code>Error</code> and <code>Notice</code> level messages.</p>
<p>If you use the <code>-q</code> flag, rclone will only produce <code>Error</code> messages.</p>
<p>If you use the <code>-v</code> flag, rclone will produce <code>Error</code>, <code>Notice</code> and <code>Info</code> messages.</p>
<p>If you use the <code>-vv</code> flag, rclone will produce <code>Error</code>, <code>Notice</code>, <code>Info</code> and <code>Debug</code> messages.</p>
<p>You can also control the log levels with the <code>--log-level</code> flag.</p>
<p>If you use the <code>--log-file=FILE</code> option, rclone will redirect <code>Error</code>, <code>Info</code> and <code>Debug</code> messages along with standard error to FILE.</p>
<p>If you use the <code>--syslog</code> flag then rclone will log to syslog and the <code>--syslog-facility</code> control which facility it uses.</p>
<p>Rclone prefixes all log messages with their level in capitals, eg INFO which makes it easy to grep the log file for different kinds of information.</p>
<h2 id="exit-code">Exit Code</h2>
<p>If any errors occurred during the command, rclone will exit with a non-zero exit code. This allows scripts to detect when rclone operations have failed.</p>
<p>During the startup phase rclone will exit immediately if an error is detected in the configuration. There will always be a log message immediately before exiting.</p>
<p>When rclone is running it will accumulate errors as it goes along, and only exit with an non-zero exit code if (after retries) there were still failed transfers. For every error counted there will be a high priority log message (visibile with <code>-q</code>) showing the message and which file caused the problem. A high priority message is also shown when starting a retry so the user can see that any previous error messages may not be valid after the retry. If rclone has done a retry it will log a high priority message if the retry was successful.</p>
<h2 id="environment-variables">Environment Variables</h2>
<p>Rclone can be configured entirely using environment variables. These can be used to set defaults for options or config file entries.</p>
<h3 id="options-6">Options</h3>
<p>Every option in rclone can have its default set by environment variable.</p>
<p>To find the name of the environment variable, first take the long option name, strip the leading <code>--</code>, change <code>-</code> to <code>_</code>, make upper case and prepend <code>RCLONE_</code>.</p>
<p>For example to always set <code>--stats 5s</code>, set the environment variable <code>RCLONE_STATS=5s</code>. If you set stats on the command line this will override the environment variable setting.</p>
<p>Or to always use the trash in drive <code>--drive-use-trash</code>, set <code>RCLONE_DRIVE_USE_TRASH=true</code>.</p>
<p>The same parser is used for the options and the environment variables so they take exactly the same form.</p>
<h3 id="config-file">Config file</h3>
<p>You can set defaults for values in the config file on an individual remote basis. If you want to use this feature, you will need to discover the name of the config items that you want. The easiest way is to run through <code>rclone config</code> by hand, then look in the config file to see what the values are (the config file can be found by looking at the help for <code>--config</code> in <code>rclone help</code>).</p>
<p>To find the name of the environment variable, you need to set, take <code>RCLONE_</code> + name of remote + <code>_</code> + name of config file option and make it all uppercase.</p>
<p>For example to configure an S3 remote named <code>mys3:</code> without a config file (using unix ways of setting environment variables):</p>
<pre><code>$ export RCLONE_CONFIG_MYS3_TYPE=s3
$ export RCLONE_CONFIG_MYS3_ACCESS_KEY_ID=XXX
$ export RCLONE_CONFIG_MYS3_SECRET_ACCESS_KEY=XXX
$ rclone lsd MYS3:
-1 2016-09-21 12:54:21 -1 my-bucket
$ rclone listremotes | grep mys3
mys3:</code></pre>
<p>Note that if you want to create a remote using environment variables you must create the <code>..._TYPE</code> variable as above.</p>
<h3 id="other-environment-variables">Other environment variables</h3>
<ul>
<li>RCLONE_CONFIG_PASS` set to contain your config file password (see <a href="#configuration-encryption">Configuration Encryption</a> section)</li>
<li>HTTP_PROXY, HTTPS_PROXY and NO_PROXY (or the lowercase versions thereof).
<ul>
<li>HTTPS_PROXY takes precedence over HTTP_PROXY for https requests.</li>
<li>The environment values may be either a complete URL or a "host[:port]" for, in which case the "http" scheme is assumed.</li>
</ul></li>
</ul>
<h1 id="configuring-rclone-on-a-remote-headless-machine">Configuring rclone on a remote / headless machine</h1>
<p>Some of the configurations (those involving oauth2) require an Internet connected web browser.</p>
<p>If you are trying to set rclone up on a remote or headless box with no browser available on it (eg a NAS or a server in a datacenter) then you will need to use an alternative means of configuration. There are two ways of doing it, described below.</p>
<h2 id="configuring-using-rclone-authorize">Configuring using rclone authorize</h2>
<p>On the headless box</p>
<pre><code>...
Remote config
Use auto config?
* Say Y if not sure
* Say N if you are working on a remote or headless machine
y) Yes
n) No
y/n> n
For this to work, you will need rclone available on a machine that has a web browser available.
Execute the following on your machine:
rclone authorize "amazon cloud drive"
Then paste the result below:
result></code></pre>
<p>Then on your main desktop machine</p>
<pre><code>rclone authorize "amazon cloud drive"
If your browser doesn't open automatically go to the following link: http://127.0.0.1:53682/auth
Log in and authorize rclone for access
Waiting for code...
Got code
Paste the following into your remote machine --->
SECRET_TOKEN
<---End paste</code></pre>
<p>Then back to the headless box, paste in the code</p>
<pre><code>result> SECRET_TOKEN
--------------------
[acd12]
client_id =
client_secret =
token = SECRET_TOKEN
--------------------
y) Yes this is OK
e) Edit this remote
d) Delete this remote
y/e/d></code></pre>
<h2 id="configuring-by-copying-the-config-file">Configuring by copying the config file</h2>
<p>Rclone stores all of its config in a single configuration file. This can easily be copied to configure a remote rclone.</p>
<p>So first configure rclone on your desktop machine</p>
<pre><code>rclone config</code></pre>
<p>to set up the config file.</p>
<p>Find the config file by running <code>rclone -h</code> and looking for the help for the <code>--config</code> option</p>
<pre><code>$ rclone -h
[snip]
--config="/home/user/.rclone.conf": Config file.
[snip]</code></pre>
<p>Now transfer it to the remote box (scp, cut paste, ftp, sftp etc) and place it in the correct place (use <code>rclone -h</code> on the remote box to find out where).</p>
<h1 id="filtering-includes-and-excludes">Filtering, includes and excludes</h1>
<p>Rclone has a sophisticated set of include and exclude rules. Some of these are based on patterns and some on other things like file size.</p>
<p>The filters are applied for the <code>copy</code>, <code>sync</code>, <code>move</code>, <code>ls</code>, <code>lsl</code>, <code>md5sum</code>, <code>sha1sum</code>, <code>size</code>, <code>delete</code> and <code>check</code> operations. Note that <code>purge</code> does not obey the filters.</p>
<p>Each path as it passes through rclone is matched against the include and exclude rules like <code>--include</code>, <code>--exclude</code>, <code>--include-from</code>, <code>--exclude-from</code>, <code>--filter</code>, or <code>--filter-from</code>. The simplest way to try them out is using the <code>ls</code> command, or <code>--dry-run</code> together with <code>-v</code>.</p>
<h2 id="patterns">Patterns</h2>
<p>The patterns used to match files for inclusion or exclusion are based on "file globs" as used by the unix shell.</p>
<p>If the pattern starts with a <code>/</code> then it only matches at the top level of the directory tree, <strong>relative to the root of the remote</strong> (not necessarily the root of the local drive). If it doesn't start with <code>/</code> then it is matched starting at the <strong>end of the path</strong>, but it will only match a complete path element:</p>
<pre><code>file.jpg - matches "file.jpg"
- matches "directory/file.jpg"
- doesn't match "afile.jpg"
- doesn't match "directory/afile.jpg"
/file.jpg - matches "file.jpg" in the root directory of the remote
- doesn't match "afile.jpg"
- doesn't match "directory/file.jpg"</code></pre>
<p><strong>Important</strong> Note that you must use <code>/</code> in patterns and not <code>\</code> even if running on Windows.</p>
<p>A <code>*</code> matches anything but not a <code>/</code>.</p>
<pre><code>*.jpg - matches "file.jpg"
- matches "directory/file.jpg"
- doesn't match "file.jpg/something"</code></pre>
<p>Use <code>**</code> to match anything, including slashes (<code>/</code>).</p>
<pre><code>dir/** - matches "dir/file.jpg"
- matches "dir/dir1/dir2/file.jpg"
- doesn't match "directory/file.jpg"
- doesn't match "adir/file.jpg"</code></pre>
<p>A <code>?</code> matches any character except a slash <code>/</code>.</p>
<pre><code>l?ss - matches "less"
- matches "lass"
- doesn't match "floss"</code></pre>
<p>A <code>[</code> and <code>]</code> together make a a character class, such as <code>[a-z]</code> or <code>[aeiou]</code> or <code>[[:alpha:]]</code>. See the <a href="https://golang.org/pkg/regexp/syntax/">go regexp docs</a> for more info on these.</p>
<pre><code>h[ae]llo - matches "hello"
- matches "hallo"
- doesn't match "hullo"</code></pre>
<p>A <code>{</code> and <code>}</code> define a choice between elements. It should contain a comma seperated list of patterns, any of which might match. These patterns can contain wildcards.</p>
<pre><code>{one,two}_potato - matches "one_potato"
- matches "two_potato"
- doesn't match "three_potato"
- doesn't match "_potato"</code></pre>
<p>Special characters can be escaped with a <code>\</code> before them.</p>
<pre><code>\*.jpg - matches "*.jpg"
\\.jpg - matches "\.jpg"
\[one\].jpg - matches "[one].jpg"</code></pre>
<p>Note also that rclone filter globs can only be used in one of the filter command line flags, not in the specification of the remote, so <code>rclone copy "remote:dir*.jpg" /path/to/dir</code> won't work - what is required is <code>rclone --include "*.jpg" copy remote:dir /path/to/dir</code></p>
<h3 id="directories">Directories</h3>
<p>Rclone keeps track of directories that could match any file patterns.</p>
<p>Eg if you add the include rule</p>
<pre><code>/a/*.jpg</code></pre>
<p>Rclone will synthesize the directory include rule</p>
<pre><code>/a/</code></pre>
<p>If you put any rules which end in <code>/</code> then it will only match directories.</p>
<p>Directory matches are <strong>only</strong> used to optimise directory access patterns - you must still match the files that you want to match. Directory matches won't optimise anything on bucket based remotes (eg s3, swift, google compute storage, b2) which don't have a concept of directory.</p>
<h3 id="differences-between-rsync-and-rclone-patterns">Differences between rsync and rclone patterns</h3>
<p>Rclone implements bash style <code>{a,b,c}</code> glob matching which rsync doesn't.</p>
<p>Rclone always does a wildcard match so <code>\</code> must always escape a <code>\</code>.</p>
<h2 id="how-the-rules-are-used">How the rules are used</h2>
<p>Rclone maintains a combined list of include rules and exclude rules.</p>
<p>Each file is matched in order, starting from the top, against the rule in the list until it finds a match. The file is then included or excluded according to the rule type.</p>
<p>If the matcher fails to find a match after testing against all the entries in the list then the path is included.</p>
<p>For example given the following rules, <code>+</code> being include, <code>-</code> being exclude,</p>
<pre><code>- secret*.jpg
+ *.jpg
+ *.png
+ file2.avi
- *</code></pre>
<p>This would include</p>
<ul>
<li><code>file1.jpg</code></li>
<li><code>file3.png</code></li>
<li><code>file2.avi</code></li>
</ul>
<p>This would exclude</p>
<ul>
<li><code>secret17.jpg</code></li>
<li>non <code>*.jpg</code> and <code>*.png</code></li>
</ul>
<p>A similar process is done on directory entries before recursing into them. This only works on remotes which have a concept of directory (Eg local, google drive, onedrive, amazon drive) and not on bucket based remotes (eg s3, swift, google compute storage, b2).</p>
<h2 id="adding-filtering-rules">Adding filtering rules</h2>
<p>Filtering rules are added with the following command line flags.</p>
<h3 id="repeating-options">Repeating options</h3>
<p>You can repeat the following options to add more than one rule of that type.</p>
<ul>
<li><code>--include</code></li>
<li><code>--include-from</code></li>
<li><code>--exclude</code></li>
<li><code>--exclude-from</code></li>
<li><code>--filter</code></li>
<li><code>--filter-from</code></li>
</ul>
<p>Note that all the options of the same type are processed together in the order above, regardless of what order they were placed on the command line.</p>
<p>So all <code>--include</code> options are processed first in the order they appeared on the command line, then all <code>--include-from</code> options etc.</p>
<p>To mix up the order includes and excludes, the <code>--filter</code> flag can be used.</p>
<h3 id="exclude---exclude-files-matching-pattern"><code>--exclude</code> - Exclude files matching pattern</h3>
<p>Add a single exclude rule with <code>--exclude</code>.</p>
<p>This flag can be repeated. See above for the order the flags are processed in.</p>
<p>Eg <code>--exclude *.bak</code> to exclude all bak files from the sync.</p>
<h3 id="exclude-from---read-exclude-patterns-from-file"><code>--exclude-from</code> - Read exclude patterns from file</h3>
<p>Add exclude rules from a file.</p>
<p>This flag can be repeated. See above for the order the flags are processed in.</p>
<p>Prepare a file like this <code>exclude-file.txt</code></p>
<pre><code># a sample exclude rule file
*.bak
file2.jpg</code></pre>
<p>Then use as <code>--exclude-from exclude-file.txt</code>. This will sync all files except those ending in <code>bak</code> and <code>file2.jpg</code>.</p>
<p>This is useful if you have a lot of rules.</p>
<h3 id="include---include-files-matching-pattern"><code>--include</code> - Include files matching pattern</h3>
<p>Add a single include rule with <code>--include</code>.</p>
<p>This flag can be repeated. See above for the order the flags are processed in.</p>
<p>Eg <code>--include *.{png,jpg}</code> to include all <code>png</code> and <code>jpg</code> files in the backup and no others.</p>
<p>This adds an implicit <code>--exclude *</code> at the very end of the filter list. This means you can mix <code>--include</code> and <code>--include-from</code> with the other filters (eg <code>--exclude</code>) but you must include all the files you want in the include statement. If this doesn't provide enough flexibility then you must use <code>--filter-from</code>.</p>
<h3 id="include-from---read-include-patterns-from-file"><code>--include-from</code> - Read include patterns from file</h3>
<p>Add include rules from a file.</p>
<p>This flag can be repeated. See above for the order the flags are processed in.</p>
<p>Prepare a file like this <code>include-file.txt</code></p>
<pre><code># a sample include rule file
*.jpg
*.png
file2.avi</code></pre>
<p>Then use as <code>--include-from include-file.txt</code>. This will sync all <code>jpg</code>, <code>png</code> files and <code>file2.avi</code>.</p>
<p>This is useful if you have a lot of rules.</p>
<p>This adds an implicit <code>--exclude *</code> at the very end of the filter list. This means you can mix <code>--include</code> and <code>--include-from</code> with the other filters (eg <code>--exclude</code>) but you must include all the files you want in the include statement. If this doesn't provide enough flexibility then you must use <code>--filter-from</code>.</p>
<h3 id="filter---add-a-file-filtering-rule"><code>--filter</code> - Add a file-filtering rule</h3>
<p>This can be used to add a single include or exclude rule. Include rules start with <code>+</code> and exclude rules start with <code>-</code>. A special rule called <code>!</code> can be used to clear the existing rules.</p>
<p>This flag can be repeated. See above for the order the flags are processed in.</p>
<p>Eg <code>--filter "- *.bak"</code> to exclude all bak files from the sync.</p>
<h3 id="filter-from---read-filtering-patterns-from-a-file"><code>--filter-from</code> - Read filtering patterns from a file</h3>
<p>Add include/exclude rules from a file.</p>
<p>This flag can be repeated. See above for the order the flags are processed in.</p>
<p>Prepare a file like this <code>filter-file.txt</code></p>
<pre><code># a sample exclude rule file
- secret*.jpg
+ *.jpg
+ *.png
+ file2.avi
# exclude everything else
- *</code></pre>
<p>Then use as <code>--filter-from filter-file.txt</code>. The rules are processed in the order that they are defined.</p>
<p>This example will include all <code>jpg</code> and <code>png</code> files, exclude any files matching <code>secret*.jpg</code> and include <code>file2.avi</code>. Everything else will be excluded from the sync.</p>
<h3 id="files-from---read-list-of-source-file-names"><code>--files-from</code> - Read list of source-file names</h3>
<p>This reads a list of file names from the file passed in and <strong>only</strong> these files are transferred. The filtering rules are ignored completely if you use this option.</p>
<p>This option can be repeated to read from more than one file. These are read in the order that they are placed on the command line.</p>
<p>Prepare a file like this <code>files-from.txt</code></p>