dam.1 (3445B)
1 .ie \n(.g .ds Aq \(aq 2 .el .ds Aq ' 3 .TH dam 1 "dam 0.1.0" 4 .SH NAME 5 dam \- Diff\-and\-merge line\-oriented text files between a local directory and a remote host over rsync 6 .SH SYNOPSIS 7 \fBdam\fR <\fB\-\-host\fR> <\fB\-\-local\fR> <\fB\-\-remote\fR> [\fB\-\-plan\fR] [\fB\-\-pull\fR] [\fB\-\-push\fR] [\fB\-\-sudo\fR] [\fB\-\-doas\fR] [\fB\-\-exit\-code\fR] [\fB\-\-timeout\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 8 .SH DESCRIPTION 9 dam (diff\-and\-merge) — sync line\-oriented text files between a local 10 directory and a remote host over rsync. 11 .PP 12 dam merges files as the de\-duplicated union of their local and remote 13 lines: local lines keep their original order and remote\-only lines are 14 appended. It is intended for list\-like data (allow\-lists, hosts files, 15 playlists, word lists), not for arbitrary documents — blank lines and 16 duplicate lines are not preserved by the merge. 17 .PP 18 \-\-local and \-\-remote may be directories or single files. When \-\-local is 19 an existing directory dam syncs the whole tree (recursing into 20 subdirectories); otherwise it treats both paths as a single file. To mirror 21 a directory into a new local location, create that directory first. 22 .PP 23 Because the merge is a union, dam never removes a line: a line deleted on 24 one side reappears from the other. Removing data is a manual edit on both 25 sides, or a one\-shot rsync. 26 .PP 27 dam has a plan/apply workflow, with three mutually exclusive modes: 28 .PP 29 \-\-plan (default) Show the changes each direction would make. Writes 30 nothing. 31 \-\-pull Apply the merge to the local directory (remote → local). 32 \-\-push Apply the merge to the remote host (local → remote). 33 .PP 34 Progress and the summary are written to stderr and the plan diff to stdout, 35 so `dam \-\-plan > changes.diff` captures just the differences. 36 .PP 37 Examples: 38 # See what would change on either side 39 dam \-\-host myserver \-\-local ~/lists \-\-remote /srv/lists 40 .PP 41 # Bring the local directory up to date 42 dam \-\-host myserver \-\-local ~/lists \-\-remote /srv/lists \-\-pull 43 .PP 44 # Bring the remote up to date 45 dam \-\-host myserver \-\-local ~/lists \-\-remote /srv/lists \-\-push 46 .PP 47 # Fail (exit 1) if the two sides have drifted — handy in CI 48 dam \-\-host myserver \-\-local ~/lists \-\-remote /srv/lists \-\-plan \-\-exit\-code 49 .SH OPTIONS 50 .TP 51 \fB\-\-host\fR \fI<HOST>\fR 52 SSH host alias (as configured in ~/.ssh/config) to sync with 53 .TP 54 \fB\-\-local\fR \fI<LOCAL>\fR 55 Local directory (or single file) containing the line\-oriented text 56 .TP 57 \fB\-\-remote\fR \fI<REMOTE>\fR 58 Remote directory (or single file) to sync from/to 59 .TP 60 \fB\-\-plan\fR 61 Show the changes each direction would make, without writing anything (the default) 62 .TP 63 \fB\-\-pull\fR 64 Apply the merge to the local directory (remote → local) 65 .TP 66 \fB\-\-push\fR 67 Apply the merge to the remote host (local → remote) 68 .TP 69 \fB\-\-sudo\fR 70 Elevate the remote rsync with `sudo` (via \-\-rsync\-path) 71 .TP 72 \fB\-\-doas\fR 73 Elevate the remote rsync with `doas` (via \-\-rsync\-path) 74 .TP 75 \fB\-\-exit\-code\fR 76 Exit with status 1 if \-\-plan finds pending changes. Processing errors always exit with status 2 77 .TP 78 \fB\-\-timeout\fR \fI<TIMEOUT>\fR [default: 30] 79 I/O timeout in seconds handed to rsync (0 disables the timeout) 80 .TP 81 \fB\-h\fR, \fB\-\-help\fR 82 Print help (see a summary with \*(Aq\-h\*(Aq) 83 .TP 84 \fB\-V\fR, \fB\-\-version\fR 85 Print version 86 .SH VERSION 87 v0.1.0