unison.1.in (17858B)
1 .\" Unison file synchronizer: man/unison.1 2 .\" Copyright 1999-2022, Unison authors 3 .\" 4 .\" This program is free software: you can redistribute it and/or modify 5 .\" it under the terms of the GNU General Public License as published by 6 .\" the Free Software Foundation, either version 3 of the License, or 7 .\" (at your option) any later version. 8 .\" 9 .\" This program is distributed in the hope that it will be useful, 10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of 11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 .\" GNU General Public License for more details. 13 .\" 14 .\" You should have received a copy of the GNU General Public License 15 .\" along with this program. If not, see <http://www.gnu.org/licenses/>. 16 .\" 17 .Dd March 17, 2022 18 .Os unison 19 .Dt UNISON 1 URM 20 .Sh NAME 21 .Nm unison 22 .Nd a multi-platform bi-directional file synchronization tool 23 .Sh SYNOPSIS 24 .Nm 25 .Op Ar options 26 .Nm 27 .Ar root1 root2 28 .Op Ar options 29 .Nm 30 .Ar profilename 31 .Op Ar options 32 .Sh DESCRIPTION 33 .Nm Unison 34 is a file-synchronization tool for POSIX-compliant systems (e.g. *BSD and 35 GNU/Linux, macOS) and Windows. It allows two replicas of a collection of files 36 and directories to be stored on different hosts (or different disks on the same 37 host), modified separately, and then brought up to date by propagating the 38 changes in each replica to the other. 39 .Pp 40 Unison has been in use for over 20 years and many people use it to synchronize 41 data they care about. 42 .Pp 43 Unison shares a number of features with other tools. Some of the distinguishing 44 features are: 45 .Bl -bullet -compact 46 .It 47 Unlike simple mirroring or backup utilities, Unison can deal with updates to 48 both replicas of a distributed directory structure. 49 .It 50 Unison works across platforms, allowing you to synchronize a Windows laptop 51 with a Unix server, for example. 52 .It 53 Unlike most distributed filesystems, Unison is a user-level program that simply 54 uses normal systems calls: there is no need to modify the kernel, to have 55 superuser privileges on either host, or to have a FUSE implementation. 56 .It 57 Unison works between any pair of machines connected to the internet, typically 58 communicating over 59 .Xr ssh 1 , 60 but also directly over TCP. It is careful with network bandwidth, and runs well 61 over slow links. Transfers of small updates to large files are optimized using 62 a compression protocol similar to 63 .Xr rsync 1 . 64 .It 65 Unison is resilient to failure. It is careful to leave the replicas and its own 66 private structures in a sensible state at all times, even in case of abnormal 67 termination or communication failures. 68 .El 69 .Sh OPTION SUMMARY 70 @OPTIONS_SHORT@ 71 .Sh OPTIONS 72 Most of the options can be given as command line arguments or in a profile. On 73 command line, but not in a profile, the options are specified with a leading 74 dash. Like this: 75 .Fl option . 76 @OPTIONS_FULL@ 77 .Sh ROOTS 78 A replica’s root tells Unison where to find a set of files to be synchronized, 79 either on the local machine or on 80 a remote host. For example, 81 .Pp 82 .Dl relative/path/of/root 83 .Pp 84 specifies a local root relative to the directory where Unison is started, while 85 .Pp 86 .Dl /absolute/path/of/root 87 .Pp 88 specifies a root relative to the top of the local filesystem, independent of 89 where Unison is running. Remote roots can begin with 90 .Sy ssh:// 91 to indicate that the remote server should be started with 92 .Xr ssh 1 : 93 .Pp 94 .Dl ssh://remotehost//absolute/path/of/root 95 .Dl ssh://user@remotehost/relative/path/of/root 96 .Pp 97 If the remote server is already running (in the socket mode), then the syntax 98 .Pp 99 .Dl socket://remotehost:portnum//absolute/path/of/root 100 .Dl socket://remotehost:portnum/relative/path/of/root 101 .Dl socket://[IPv6literal]:portnum/path 102 .Pp 103 is used to specify the hostname and the port that the client Unison should use 104 to contact it. Syntax 105 .Pp 106 .Dl socket://{path/of/socket}//absolute/path/of/root 107 .Dl socket://{path/of/socket}/relative/path/of/root 108 .Pp 109 is used to specify the Unix domain socket the client Unison should use to 110 contact the server. 111 .Pp 112 The syntax for roots is based on that of URIs (described in RFC 2396). The full 113 grammar is: 114 .Bd -literal 115 replica ::= [protocol:]//[user@][host][:port][/path] 116 | path 117 118 protocol ::= file 119 | socket 120 | ssh 121 122 user ::= [-_a-zA-Z0-9%@]+ 123 124 host ::= [-_a-zA-Z0-9.]+ 125 | \e[ [a-f0-9:.]+ zone? \e] IPv6 literals (no future format). 126 | { [^}]+ } For Unix domain sockets only. 127 128 zone ::= %[-_a-zA-Z0-9~%.]+ 129 130 port ::= [0-9]+ 131 132 .Ed 133 When path is given without any protocol prefix, the protocol is assumed to be 134 .Sy file: . 135 Under Windows, it is possible to synchronize with a remote directory using the 136 .Sy file: 137 protocol over the Windows Network Neighborhood. For example, 138 .Pp 139 .Dl unison foo //host/drive/bar 140 .Pp 141 synchronizes the local directory 142 .Pa foo 143 with the directory 144 .Pa drive:\ebar 145 on the machine 146 .Sy host , 147 provided that host is accessible via Network Neighborhood. When the 148 .Sy file: 149 protocol is used in this way, there is no need for a Unison server to be 150 running on the remote host. However, running Unison this way is only a good 151 idea if the remote host is reached by a very fast network connection, since the 152 full contents of every file in the remote replica will have to be transferred 153 to the local machine to detect updates. 154 .Sh PATHS 155 A path refers to a point within a set of files being synchronized; it is 156 specified relative to the root of the replica. Formally, a path is just a 157 sequence of names, separated by /. Note that the path separator character is 158 always a forward slash, no matter what operating system Unison is running on. 159 The empty path (i.e., the empty sequence of names) denotes the whole replica. 160 .Sh PATH SPECIFICATION 161 Several Unison preferences (e.g., 162 .Sy ignore/ignorenot , follow , sortfirst/sortlast , backup , merge , 163 etc.) specify individual paths or sets of paths. These preferences share a 164 common syntax based on regular expressions. Each preference is associated with 165 a list of path patterns; the paths specified are those that match any one of 166 the path pattern. 167 .Pp 168 Each pattern can have one of three forms. The most general form is a Posix 169 extended regular expression introduced by the keyword 170 .Sy Regex . 171 (The collating sequences and character classes of full Posix regexps are not 172 currently supported.) 173 .Pp 174 .Dl Cm Regex Ar regexp 175 .Pp 176 For convenience, three other styles of pattern are also recognized: 177 .Pp 178 .Dl Cm Name Ar name 179 .Pp 180 matches any path in which the last component matches 181 .Ar name , 182 .Pp 183 .Dl Cm Path Ar path 184 .Pp 185 matches exactly the path 186 .Ar path , 187 and 188 .Pp 189 .Dl Cm BelowPath Ar path 190 .Pp 191 matches the path 192 .Ar path 193 and any path below. The 194 .Ar name 195 and 196 .Ar path 197 arguments of the latter forms of patterns are 198 .Em not 199 regular expressions. Instead, standard 200 .Dq globbing 201 conventions can be used in 202 .Ar name 203 and 204 .Ar path : 205 .Bl -dash 206 .It 207 a 208 .Sy "*" 209 matches any sequence of characters not including / (and not beginning with ., 210 when used at the beginning of a 211 .Ar name ) 212 .It 213 a 214 .Sy \&? 215 matches any single character except / (and leading .) 216 .It 217 .Sy [xyz] 218 matches any character from the set {x, y, z} 219 .It 220 .Sy {a,bb,ccc} 221 matches any one of a, bb, or ccc. (Be careful not to put extra spaces after the 222 commas: these will be interpreted literally as part of the strings to be 223 matched!) 224 .El 225 .Pp 226 The path separator in path patterns is always the forward-slash character 227 .Dq / 228 — even when the client or server is running under Windows, where the normal 229 separator character is a backslash. This makes it possible to use the same set 230 of path patterns for both Unix and Windows file systems. 231 .Pp 232 A path specification may be followed by the separator 233 .Dq " -> " 234 itself followed by a string which will be associated to the matching paths: 235 .Pp 236 .Dl Cm Path Ar path No -> Ar "associated string" 237 .Pp 238 Not all pathspec preferences use these associated strings but all pathspec 239 preferences are parsed identically and the strings may be ignored. Only the 240 last match of the separator string on the line is used as a delimiter. Thus to 241 allow a path specification to contain the separator string, append an 242 associated string to it, even if it is not used. The associated string cannot 243 contain the separator string. 244 .Sh PROFILES 245 A profile is a text file that specifies permanent settings for roots, paths, 246 ignore patterns, and other preferences, so that they do not need to be typed at 247 the command line every time Unison is run. Profiles should reside in the 248 .Pa .unison 249 directory on the client machine. If Unison is started with just one argument 250 .Ar name 251 on the 252 command line, it looks for a profile called 253 .Em name Ns Sy .prf 254 in the 255 .Pa .unison 256 directory. If it is started with no arguments, it scans the 257 .Pa .unison 258 directory for files whose names end in 259 .Sy .prf 260 and offers a menu (when using the graphical user interface; for the text 261 interface, you have to use the 262 .Fl i 263 option). If a file named 264 .Pa default.prf 265 is found, its settings will be used as the default preferences. 266 .Pp 267 To set the value of a preference 268 .Sy p 269 permanently, add to the appropriate profile a line of the form 270 .Pp 271 .Dl p = true 272 .Pp 273 for a boolean flag or 274 .Pp 275 .Dl p = <value> 276 .Pp 277 for a preference of any other type. 278 Whitespaces around 279 .Sy p 280 and the value are ignored. A profile may also include blank lines and lines 281 beginning with #; both are ignored. 282 .Pp 283 When Unison starts, it first reads the profile and then the command line, so 284 command-line options will override settings from the profile. 285 .Sh TERMINATION 286 When not synchronizing continuously, the text interface terminates when 287 synchronization is finished normally or due to a fatal error occurring. 288 .Pp 289 In the text interface, to interrupt synchronization before it is finished, 290 press 291 .Sy Ctrl-C 292 (or send signal 293 .Sy SIGINT 294 or 295 .Sy SIGTERM ) . 296 This will interrupt update propagation as quickly as possible but still 297 complete proper cleanup. If the process does not stop even after pressing 298 .Sy Ctrl-C 299 then keep doing it repeatedly. This will bypass cleanup procedures and 300 terminates the process forcibly (similar to 301 .Sy SIGKILL ) . 302 Doing so may leave the archives or replicas in an inconsistent state or locked. 303 .Pp 304 When synchronizing continuously (time interval repeat or with filesystem 305 monitoring), interrupting with 306 .Sy Ctrl-C 307 or with signal 308 .Sy SIGINT 309 or 310 .Sy SIGTERM 311 works the same way as described above and will additionally stop the continuous 312 process. To stop only the continuous process and let the last synchronization 313 complete normally, send signal 314 .Sy SIGUSR2 315 instead. 316 .Sh ENVIRONMENT 317 .Bl -tag 318 .It Ev UNISON 319 Unison stores a variety of information in a private directory on each host. If 320 the environment variable 321 .Sy UNISON 322 is defined, then its value will be used as the path for this directory. This 323 can be just a name, or a path. If 324 .Sy UNISON 325 is not defined, then the directory depends on which operating system you are 326 using. In Unix, the default is to use 327 .Pa $HOME/.unison . 328 In Windows, if the environment variable 329 .Sy USERPROFILE 330 is defined, then the directory will be 331 .Pa $USERPROFILE\e.unison ; 332 otherwise, it will be 333 .Pa c:\e.unison . 334 On macOS, 335 .Pa $HOME/.unison 336 will be used if it is present, but 337 .Pa "$HOME/Library/Application Support/Unison" 338 will be created and used by default. 339 .It Ev UNISONLOCALHOSTNAME 340 The function that finds the canonical hostname of the local host (which is 341 used, for example, in calculating the name of the archive file used to remember 342 which files have been synchronized) normally uses the 343 .Sy gethostname 344 operating system call. However, if the environment variable 345 .Sy UNISONLOCALHOSTNAME 346 is set, its value will be used instead. This makes it easier to use Unison in 347 situations where a machine’s name changes frequently (e.g., because it is a 348 laptop and gets moved around a lot). 349 .It Ev UNISONBACKUPDIR 350 When backups are stored centrally, the directory used to hold them is 351 controlled by the preference 352 .Sy backupdir 353 and the environment variable 354 .Sy UNISONBACKUPDIR . 355 If both are specified then the environment variable overrides the preference. 356 If neither of these are set, then the directory 357 .Pa $UNISON/backup 358 is used (see environment variable 359 .Sy UNISON 360 above). 361 .It Ev PAGER 362 Used by the text interface as the pager when displaying the differences between 363 changed files. 364 .It Ev NO_COLOR 365 If the environment variable 366 .Sy NO_COLOR 367 is set then Unison's text interface will not produce any color output by 368 default. The 369 .Sy color 370 preference overrides this environment variable. 371 .El 372 .Sh FILES 373 .Bl -tag -compact 374 .It Pa ~/.unison 375 Unison stores a variety of information in a private directory on each host. 376 This is the default path of this private directory. This path may be changed by 377 the 378 .Sy UNISON 379 environment variable. 380 .Pp 381 .It Pa ~/.unison/*.prf 382 Profile files. Each profile is stored in a file named 383 .Em profilename Ns Sy .prf . 384 .Pp 385 .It Pa ~/.unison/ar* 386 .It Pa ~/.unison/tm* 387 .It Pa ~/.unison/sc* 388 Main and temporary archive files. These files may be deleted if you know what 389 you are doing. Deleting an archive file is equivalent to using the 390 .Fl ignorearchives 391 option. 392 .Pp 393 .It Pa ~/.unison/fp* 394 Fingerprint cache files. These files may be safely deleted. Keep in mind that 395 deleting a fingerprint cache file means that any unsynchronized changes must be 396 scanned again. Depending on your replicas, this may mean scanning gigabytes of 397 file contents. 398 .Pp 399 .It Pa ~/.unison/lk* 400 Lock files indicating a running Unison process. These files may be deleted if 401 you are careful and know that there is no Unison process currently running. 402 Deleting a lock file is equivalent to using the 403 .Fl ignorelocks 404 option. 405 .El 406 .Sh EXAMPLES 407 .Bl -tag -width "" 408 .It Sy Synchronize two local directories 409 .Pp 410 .Dl unison path/to/dir1 /dir2 411 .Pp 412 This command synchronizes two local directories using the default options. 413 Default options are defined by Unison and can be overridden by user in a 414 profile called 415 .Dq default , 416 which is by default stored in file 417 .Pa ~/.unison/default.prf 418 .It Sy Synchronize a local and a remote directory 419 .Pp 420 .Dl unison local/dir ssh://user@host//absolute/path 421 .Pp 422 This command synchronizes a local directory (here specified by a relative path) 423 and a remote directory (here specified by an absolute path) using 424 .Xr ssh 1 425 and the default options (see example above). 426 .It Sy Synchronize with all options specified in a profile 427 .Pp 428 .Dl unison profilename 429 .Pp 430 This command reads all the options from the profile named 431 .Dq profilename 432 and synchronizes according to those options. 433 .It Sy Synchronize with options specified in a profile and roots on command line 434 .Pp 435 .Dl unison profilename /path/to/dir ssh://host/path/on/server 436 .Pp 437 This command reads all options from the profile named 438 .Dq profilename 439 with only the roots specified on the command line. Roots must not be specified 440 in the profile as the roots from command line will not override roots in the 441 profile, rather append to the list of roots. 442 .It Sy Synchronize automatically 443 .Pp 444 .Dl unison -batch /path/to/dir ssh://host/path/on/server 445 .Pp 446 This command synchronizes all non-conflicting changes automatically, once. 447 .It Sy Synchronize continuously 448 .Pp 449 .Dl unison -repeat watch /path/to/dir ssh://host/path/on/server 450 .Pp 451 This command first fully synchronizes the roots and then remains dormant, 452 waiting for any file changes within either root and then automatically 453 synchronizes these changes. This also works in a profile 454 .No ( Ns Sy "repeat = watch" ) . 455 If the filesystem monitoring helper program is not available or not desired for 456 other reasons, it is possible to make Unison synchronize repeatedly with a 457 defined time interval: 458 .Pp 459 .Dl unison -repeat 60 /path/to/dir ssh://host/path/on/server 460 .Pp 461 This command synchronizes every 60 seconds. Using 462 .Fl repeat 463 implies 464 .Fl batch . 465 .Pp 466 Currently, continuous synchronization is not possible when using the GUI. 467 .El 468 .Sh DIAGNOSTICS 469 When running in the textual mode, Unison returns an exit status, which 470 describes whether, and at which level, the synchronization was successful. The 471 exit status could be useful when Unison is invoked from a script. Currently, 472 there are four possible values for the exit status: 473 .Bl -tag -width 1m 474 .It 0 475 successful synchronization; everything is up-to-date now. 476 .It 1 477 some files were skipped, but all file transfers were successful. 478 .It 2 479 non-fatal failures occurred during file transfer. 480 .It 3 481 a fatal error occurred, or the execution was interrupted. 482 .El 483 .Pp 484 The graphical interface does not return any useful information through the exit 485 status. 486 .Sh COMPATIBILITY 487 If you are using Unison versions \*(>= 2.52 on all machines, you do not have to 488 do anything extra for compatibility. 489 .Pp 490 Historically (versions \*(Lt 2.52), Unison versions had to be matched 491 relatively exactly for them to work together. Additionally, the version of 492 compiler used to build Unison also had significant relevance for compatibility. 493 .Pp 494 As of version 2.52, Unison has a degree of backward and forward compatibility. 495 This means three things. First, it is possible for local and remote machines to 496 run a different version of Unison. Second, it is possible for local and remote 497 machines to run a version (same or different) of Unison built with a different 498 version of compiler. Lastly, it is possible to upgrade Unison on the local 499 machine and keep the existing archive. 500 .Pp 501 For more information on co-existence of versions \*(Lt 2.52 and \*(>= 2.52, see 502 .Lk https://github.com/bcpierce00/unison/wiki/2.52-Migration-Guide 503 .Sh SEE ALSO 504 There is a full user manual (pdf, html and txt) included with Unison and 505 available online. Depending on your operating system, this manual may have been 506 installed at 507 .Pa /usr/share/doc/unison/ 508 or a similar location. The manual can also be read in the GUI (look in the Help 509 menu) or on the command line by 510 .Sy unison -doc all 511 (you probably want to pipe the output to a pager). 512 .Pp 513 .Lk https://github.com/bcpierce00/unison 514 .\" .Sh STANDARDS 515 .\" .Sh HISTORY 516 .\" .Sh BUGS