syncdot 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
syncdot-1.0.0/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ariel Shatil
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
syncdot-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,648 @@
1
+ Metadata-Version: 2.4
2
+ Name: syncdot
3
+ Version: 1.0.0
4
+ Summary: Bidirectional dotfiles sync with git, profiles, and templating
5
+ Author: Ariel Shatil
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/denomolo/syncdot
8
+ Project-URL: Changelog, https://github.com/denomolo/syncdot/blob/main/CHANGELOG.md
9
+ Project-URL: Issues, https://github.com/denomolo/syncdot/issues
10
+ Keywords: dotfiles,sync,git,jinja2,config,systemd
11
+ Classifier: Development Status :: 5 - Production/Stable
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Intended Audience :: System Administrators
15
+ Classifier: Operating System :: POSIX :: Linux
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Topic :: System :: Systems Administration
22
+ Classifier: Topic :: Utilities
23
+ Requires-Python: >=3.11
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Requires-Dist: jinja2>=3.1
27
+ Requires-Dist: pyyaml>=6.0
28
+ Requires-Dist: click>=8.1
29
+ Provides-Extra: dev
30
+ Requires-Dist: pytest>=8; extra == "dev"
31
+ Requires-Dist: build>=1.2; extra == "dev"
32
+ Requires-Dist: twine>=6; extra == "dev"
33
+ Dynamic: license-file
34
+
35
+ <h1 align="center">
36
+ <img src="https://raw.githubusercontent.com/denomolo/syncdot/main/assets/logo.svg" alt="syncdot" width="600">
37
+ </h1>
38
+
39
+ Author's Note:
40
+ I wanted to play a bit with Claude and see what it could do. Thought of building something that I could use on a daily basis. I've been a fan of chezmoi for a while but remembering the sync model and the syntax every time that I just wanted to backup or pull a file made me abandon it long ago.
41
+
42
+ I built this with Claude code using these self imposed rules:
43
+ * I decide on syntax.
44
+ * I decide on the logic.
45
+ * Python is the language of choice.
46
+ * No handling of secrets or binary files.
47
+ * Keep it as simple as possible.
48
+
49
+ Let me know if you like it.
50
+ ##
51
+
52
+ Bidirectional dotfile sync backed by a git repo, with per-machine profiles
53
+ (git branches) and Jinja2 templating.
54
+
55
+ Edit a dotfile on any machine and `syncdot sync` pushes it to your dotfiles
56
+ repo; edit it in the repo (or on another machine) and the next sync pulls it
57
+ down. syncdot remembers what it last wrote to each file, so it can tell
58
+ which side changed and only asks a conflict policy to decide when both did.
59
+
60
+ ## Contents
61
+
62
+ - [Install](#install)
63
+ - [Quick start](#quick-start)
64
+ - [Commands](#commands)
65
+ - [Automatic sync](#automatic-sync)
66
+ - [Dotfiles repo layout](#dotfiles-repo-layout)
67
+ - [Profiles](#profiles)
68
+ - [Templates](#templates)
69
+ - [Environment variables](#environment-variables)
70
+ - [Conflicts](#conflicts)
71
+ - [Configuration](#configuration)
72
+ - [What is not synced](#what-is-not-synced)
73
+ - [Development](#development)
74
+ - [Changelog](#changelog)
75
+ - [License](#license)
76
+ - [How it works](#how-it-works)
77
+
78
+ ## Install
79
+
80
+ **Requirements:** Python 3.11+, [pipx](https://pipx.pypa.io/), git, and an
81
+ SSH key on your GitHub account for pushing to your dotfiles repo
82
+ (`ssh -T git@github.com` should greet you).
83
+ The optional auto-sync service needs systemd.
84
+
85
+ ### 1. Install the tool
86
+
87
+ ```sh
88
+ pipx install syncdot
89
+ syncdot --version
90
+ ```
91
+
92
+ `pipx upgrade syncdot` upgrades it later. To install straight from GitHub
93
+ instead: `pipx install git+https://github.com/denomolo/syncdot.git`, or
94
+ from a local checkout: `pipx install --force .`
95
+
96
+ **Coming from dotsync?** syncdot was called dotsync up to 0.8.0. Install
97
+ syncdot, run any `syncdot` command, and your config, clone and state move
98
+ to syncdot's locations automatically (`~/.config/syncdot`,
99
+ `~/.local/share/syncdot`, `~/.local/state/syncdot`); then
100
+ `pipx uninstall dotsync`. If you used the login service, run
101
+ `syncdot service install` once to replace it.
102
+
103
+ ### 2. Create your dotfiles repo
104
+
105
+ Your dotfiles live in **your own** repo, separate from this one. Create a
106
+ new private repo on GitHub (e.g. `<you>/dotfiles`) and leave it **completely
107
+ empty** — no README, license or .gitignore — because syncdot creates the
108
+ first commit itself.
109
+
110
+ ### 3. Set up syncdot
111
+
112
+ On every machine, the first one included:
113
+
114
+ ```sh
115
+ syncdot init <you>/dotfiles
116
+ ```
117
+
118
+ The repo can be `owner/repo`, an HTTPS GitHub URL (both converted to SSH so
119
+ your key is used) or any git URL. An empty repo is set up as a new syncdot
120
+ repo; an existing one is cloned. If you haven't created the GitHub repo
121
+ yet, `syncdot init <you>/dotfiles --new` starts one locally and pushes it
122
+ on your first `syncdot add`.
123
+
124
+ `init` writes `~/.config/syncdot/config.yaml` and the clone, and asks
125
+ whether to sync automatically at login (off unless you say yes; see
126
+ [Automatic sync](#automatic-sync)). It never touches the files in your home
127
+ directory. Use `--profile <name>` to start on a profile other than `base`.
128
+ (Before 0.8.0 this was `install --repo-url …`, which still works.)
129
+
130
+ ## Quick start
131
+
132
+ ```sh
133
+ # Start tracking files (one commit, pushed to GitHub)
134
+ syncdot add ~/.vimrc ~/.bashrc ~/.config/kitty
135
+
136
+ # See what changed
137
+ syncdot status
138
+
139
+ # Sync both ways
140
+ syncdot sync
141
+ ```
142
+
143
+ On another machine, after `syncdot init`, nothing is synced until you
144
+ say so. `sync` only handles files that were already synced on that
145
+ machine; everything else is listed by `status` and left alone:
146
+
147
+ ```sh
148
+ syncdot status # what's in the repo, and what differs here
149
+ syncdot pull # take the repo's version of everything (asks before
150
+ # overwriting anything that differs here)
151
+ syncdot pull ~/.config/kitty # ...or just some files
152
+ syncdot push ~/.bashrc # keep this machine's version instead
153
+ ```
154
+
155
+ After a file has been pulled or pushed once on a machine, `sync` keeps it
156
+ in step from then on. The same goes for files that another machine adds to
157
+ the repo later: `sync` reports them until you `pull` them.
158
+
159
+ ## Commands
160
+
161
+ | Command | What it does |
162
+ | --- | --- |
163
+ | `syncdot init REPO [--new]` | Set syncdot up on this machine: clone (or start) your dotfiles repo and write the config. |
164
+ | `syncdot sync` | Two-way sync of every tracked file (see [How it works](#how-it-works)). |
165
+ | `syncdot status [PATH...] [--diff]` | Show what `sync` would do for each file (or just `PATH`s), including changes waiting on GitHub, without changing anything; `--diff` shows how files differ. |
166
+ | `syncdot push [PATH...]` | Copy this machine's version to the repo, for every file or just `PATH`s. Commits and pushes. |
167
+ | `syncdot pull [PATH...] [--yes]` | Copy the repo's version to this machine, for every file or just `PATH`s; asks before overwriting local changes. |
168
+ | `syncdot add PATH... [--remote R] [--allow-private]` | Start tracking files or directories from disk. |
169
+ | `syncdot checkout REMOTE... [--local L] [--force]` | Start tracking files that are already in the repo, writing them to disk. |
170
+ | `syncdot remove PATH...` | Stop tracking files or directories. The copies on disk are kept. |
171
+ | `syncdot var list \| set NAME=VALUE... \| unset NAME...` | Manage [template variables](#variables). |
172
+ | `syncdot env list \| set NAME=VALUE... \| unset NAME... \| hook` | Manage [environment variables](#environment-variables) for your session. |
173
+ | `syncdot profile list \| set NAME \| new NAME` | Manage [profiles](#profiles). |
174
+ | `syncdot service install \| uninstall \| status` | Opt in to syncing automatically at login ([details](#automatic-sync)). |
175
+ | `syncdot --version` | Print the installed version. |
176
+
177
+ `sync`, `push`, `pull`, `add`, `checkout`, `remove`, `var set|unset` and
178
+ `env set|unset` accept `--dry-run` to show what would happen without
179
+ changing anything: incoming changes from GitHub are fetched and previewed
180
+ (including merging `base` into a profile) in a temporary copy, so your
181
+ files, the local clone's branches and its working tree stay exactly as
182
+ they were. `sync`, `push` and `pull` accept `-v` to list unchanged files
183
+ too.
184
+
185
+ Only one syncdot runs at a time. If you start a command while another one
186
+ is running (for example the background `sync`), it waits for it to
187
+ finish, and gives up after two minutes.
188
+
189
+ ### Output symbols
190
+
191
+ | Symbol | Meaning |
192
+ | --- | --- |
193
+ | `↑` | disk → repo (pushed) |
194
+ | `↓` | repo → disk (pulled) |
195
+ | `!` | conflict, resolved by the configured policy (shown in brackets) |
196
+ | `−` | no longer tracked |
197
+ | `·` | already in sync |
198
+ | `-` | skipped (e.g. binary file) |
199
+
200
+ ### `add`
201
+
202
+ ```sh
203
+ syncdot add ~/.vimrc ~/.config/environment.d
204
+ syncdot add ~/.config/foo/*.conf
205
+ syncdot add '~/.config/foo/*.conf' # quoted: syncdot expands it
206
+ syncdot add /etc/hosts --remote system/ # outside ~ needs --remote
207
+ ```
208
+
209
+ - Each path is stored under `files/` at its location relative to your home
210
+ directory: `~/.config/environment.d` → `files/.config/environment.d`.
211
+ - `--remote R` picks the location under `files/` instead. If `R` ends with
212
+ `/`, is an existing directory, or several paths are given, each path keeps
213
+ its name inside `R`.
214
+ - Everything is added in one commit. Paths that can't be added (missing,
215
+ already tracked, binary, private, a symlink, or two paths that would land
216
+ on the same repo path) are reported, the rest are still added, and the
217
+ command exits with status 1.
218
+ - Private files are refused: a file only you can access (no group or other
219
+ permissions, e.g. mode `600`), a directory like that (e.g. `~/.ssh` at
220
+ `700`), or a directory containing such a file. They usually hold secrets,
221
+ and their contents would end up in your dotfiles repo. Pass
222
+ `--allow-private` to track them anyway.
223
+
224
+ ### `checkout`
225
+
226
+ The reverse of `add`, for setting up a new machine from a populated repo.
227
+
228
+ ```sh
229
+ syncdot checkout .vimrc # files/.vimrc → ~/.vimrc
230
+ syncdot checkout '.config/*' # glob, matched in the repo
231
+ syncdot checkout nvim --local ~/.config/nvim # choose where it goes
232
+ syncdot checkout .bashrc --force # overwrite a different local file
233
+ ```
234
+
235
+ - `REMOTE` paths are relative to `files/` (a leading `files/` is accepted).
236
+ - `--local` defaults to `~/<REMOTE>`, with any `.j2` suffix dropped.
237
+ - An existing local file with **the same** content is simply tracked. One
238
+ with **different** content is left alone and reported, unless you pass
239
+ `--force`.
240
+
241
+ ### `status`
242
+
243
+ ```sh
244
+ syncdot status # every tracked file
245
+ syncdot status ~/.vimrc # just one (or several, or a quoted glob)
246
+ syncdot status ~/.config/kitty --diff
247
+ ```
248
+
249
+ `--diff` prints a unified diff for each file that differs, from the repo's
250
+ version (rendered, for templates) to this machine's: `-` lines are only in
251
+ the repo, `+` lines only here. Directories are compared file by file, and
252
+ binary files are only reported as different.
253
+
254
+ `status` fetches from GitHub first, so it includes changes that `sync`
255
+ would pull (previewed in a temporary copy, like `--dry-run`; nothing is
256
+ merged). `--no-fetch` compares with the local clone only, and offline it
257
+ warns and does that anyway. For scripts, `--exit-code` exits with 3 when
258
+ anything isn't in sync and 0 when everything is.
259
+
260
+ ### `push` and `pull`
261
+
262
+ ```sh
263
+ syncdot push ~/.config/starship.toml
264
+ syncdot pull '~/.config/foo/*' # also restores files deleted from disk
265
+ ```
266
+
267
+ Without paths they act on every tracked file. Paths are files or
268
+ directories on disk as listed in the manifest; quoted globs are matched
269
+ against tracked paths rather than the filesystem. A file *inside* a tracked
270
+ directory is rejected — use the directory. `remove` takes paths the same
271
+ way.
272
+
273
+ `pull` never silently loses local work: if a file has changes that aren't
274
+ in the repo (edited since it was last synced, or a local file that was
275
+ never synced, like a distribution's default `.bashrc`), `pull` lists those
276
+ files and asks before overwriting them. Files that are simply out of date
277
+ are pulled without asking. `--yes` skips the question; in a script without
278
+ `--yes`, `pull` refuses and changes nothing.
279
+
280
+ ### Exit codes
281
+
282
+ `0` success, `1` error (including any file a `sync`, `push` or `pull`
283
+ couldn't handle), `2` invalid command-line usage, and `3` from
284
+ `status --exit-code` when something isn't in sync.
285
+
286
+ ## Automatic sync
287
+
288
+ Automatic sync is off unless you opt in, and then it only runs at login:
289
+
290
+ ```sh
291
+ syncdot service install # sync at every login, after the network is up
292
+ syncdot service status
293
+ syncdot service uninstall
294
+ ```
295
+
296
+ This installs a systemd user unit, `~/.config/systemd/user/syncdot.service`,
297
+ that runs `syncdot sync` once per login; it doesn't run a sync right away.
298
+ Output goes to the journal: `journalctl --user -u syncdot`. Without systemd,
299
+ run `syncdot sync` from your shell's startup files instead. (syncdot 0.6.0
300
+ also installed an hourly `syncdot.timer`; `service install` and `uninstall`
301
+ remove it.)
302
+
303
+ ## Dotfiles repo layout
304
+
305
+ Every branch of your dotfiles repo has the same layout:
306
+
307
+ ```
308
+ files/ # the dotfiles themselves
309
+ .vimrc
310
+ .config/kitty/kitty.conf
311
+ .gitconfig.j2 # rendered as a template
312
+ vars.yaml # variables for templates
313
+ manifest.yaml # which repo path goes where on disk
314
+ README.md
315
+ ```
316
+
317
+ `manifest.yaml` maps each repo path (`source`) to its location on disk
318
+ (`dest`). `add`, `checkout` and `remove` maintain it for you, keeping any
319
+ comments, but you can edit it by hand:
320
+
321
+ ```yaml
322
+ files:
323
+ - source: files/.vimrc
324
+ dest: ~/.vimrc
325
+
326
+ - source: files/.config/kitty
327
+ dest: ~/.config/kitty
328
+ ```
329
+
330
+ See [`manifest.yaml.example`](manifest.yaml.example) and
331
+ [`vars.yaml.example`](vars.yaml.example).
332
+
333
+ ## Profiles
334
+
335
+ A profile is a git branch. `base` holds what every machine shares; each
336
+ other profile is a `profiles/<name>` branch that starts as a copy of `base`
337
+ and adds its own commits on top.
338
+
339
+ ```mermaid
340
+ %%{init: {"gitGraph": {"mainBranchName": "base", "rotateCommitLabel": false, "parallelCommits": false}}}%%
341
+ gitGraph
342
+ commit id: "add .vimrc"
343
+ commit id: "add kitty"
344
+ branch profiles/laptop
345
+ commit id: "laptop: bigger font"
346
+ checkout base
347
+ commit id: "add starship"
348
+ checkout profiles/laptop
349
+ merge base id: "sync merges base"
350
+ ```
351
+
352
+ ```sh
353
+ syncdot profile new laptop # create profiles/laptop from base
354
+ syncdot profile set laptop # make it this machine's active profile
355
+ syncdot pull # apply it to disk
356
+ syncdot profile list # base, laptop ← active
357
+ ```
358
+
359
+ - To change a file or variable for one profile, edit it on that profile's
360
+ branch: anything you push while the profile is active is committed there.
361
+ - Every `sync` (and `pull`/`checkout`) merges `base` into the active profile
362
+ branch, so shared changes reach every profile.
363
+ - If the merge conflicts (both `base` and the profile changed the same
364
+ lines), syncdot aborts it, warns you with the `git merge` command to run
365
+ in the repo clone, and leaves the branch and your files untouched until
366
+ you resolve it.
367
+
368
+ ## Templates
369
+
370
+ Files ending in `.j2` are rendered with [Jinja2](https://jinja.palletsprojects.com/)
371
+ using the variables in `vars.yaml` before being written to disk. Undefined
372
+ variables are an error rather than silently empty.
373
+
374
+ ```yaml
375
+ # vars.yaml
376
+ email: you@example.com
377
+ editor: nvim
378
+ ```
379
+
380
+ ```ini
381
+ # files/.gitconfig.j2
382
+ [user]
383
+ email = {{ email }}
384
+ [core]
385
+ editor = {{ editor }}
386
+ ```
387
+
388
+ Directories are always copied verbatim, never rendered.
389
+
390
+ ### Variables
391
+
392
+ Manage `vars.yaml` with `syncdot var` instead of editing it in the repo:
393
+
394
+ ```sh
395
+ syncdot var set fullname="Ariel Shatil" email=ariel@example.com
396
+ syncdot var list
397
+ syncdot var unset editor
398
+ ```
399
+
400
+ - `set` and `unset` change `vars.yaml` on the **active profile's branch**,
401
+ re-render the templates on disk, and commit and push, so other machines
402
+ get the change on their next sync. Comments in `vars.yaml` are kept.
403
+ - Values are stored as strings: `port=22` and `debug=true` stay `"22"` and
404
+ `"true"`. Add `--yaml` to parse values as YAML instead, for numbers,
405
+ booleans or lists (`--yaml retries=3 hosts="[a, b]"`).
406
+ - `unset` refuses a variable that a tracked template still uses, since the
407
+ template could no longer render; `--force` unsets it anyway.
408
+ - Both take `--dry-run`. Names are letters, digits and `_`, not starting
409
+ with a digit.
410
+ - On a profile, `set` overrides the `base` value for that profile only, and
411
+ later changes to `base` still merge in. `unset` on a profile removes the
412
+ variable for that profile; it doesn't fall back to `base`'s value.
413
+
414
+ Templated files only flow **repo → disk**. If you edit the rendered file on
415
+ disk (e.g. `~/.gitconfig`), `sync` and `push` report an error instead of
416
+ copying it over the template, and leave both sides alone. Make the change in
417
+ the `.j2` file in the repo, or run `syncdot pull <path>` to discard the
418
+ local edit. See
419
+ [`dot_gitconfig.j2.example`](dot_gitconfig.j2.example).
420
+
421
+ ## Environment variables
422
+
423
+ `syncdot env` manages environment variables for your session, such as
424
+ `EDITOR` or `GIT_AUTHOR_EMAIL`. They live in their own `env:` section of
425
+ `vars.yaml`, separate from template variables, so only what you list there
426
+ is exported:
427
+
428
+ ```sh
429
+ syncdot env set EDITOR=nvim BROWSER=firefox
430
+ syncdot env set GIT_AUTHOR_EMAIL='{{ email }}' # reuse a template variable
431
+ syncdot env list
432
+ syncdot env unset BROWSER
433
+ ```
434
+
435
+ ```yaml
436
+ # vars.yaml
437
+ email: ariel@example.com
438
+ env:
439
+ EDITOR: nvim
440
+ GIT_AUTHOR_EMAIL: '{{ email }}'
441
+ ```
442
+
443
+ On every `sync`, `pull`, `checkout` and `var`/`env` change, syncdot writes
444
+ them to **`~/.config/environment.d/99-env.conf`**, one `KEY="value"` per
445
+ line, a format both systemd and POSIX shells read:
446
+
447
+ - **systemd user session:** reads the file by itself, so user services and
448
+ the graphical session on desktops started through systemd (e.g. GNOME,
449
+ KDE Plasma) get the variables. syncdot also updates the running session,
450
+ so newly started services see changes straight away.
451
+ - **Shells** (TTYs, SSH, systems without systemd): add the line printed by
452
+ `syncdot env hook` to `~/.profile`, and to `~/.bashrc` / `~/.zshrc` to
453
+ have it in every interactive shell:
454
+
455
+ ```sh
456
+ [ -r ~/.config/environment.d/99-env.conf ] && { set -a; . ~/.config/environment.d/99-env.conf; set +a; }
457
+ ```
458
+
459
+ - Values may use template variables (`'{{ email }}'`); quote them with
460
+ single quotes so your shell leaves the braces alone. `var unset` refuses
461
+ a template variable that an env value still uses.
462
+ - Values can't contain newlines or `$` (systemd would expand it), so
463
+ `PATH`-style expansion isn't supported. Variables your session manages
464
+ (`PATH`, `HOME`, `USER`, `SHELL`, `DISPLAY`, `XDG_RUNTIME_DIR`, `LD_*`
465
+ and similar) are refused.
466
+ - systemd applies `environment.d` files in name order, later ones winning.
467
+ Many distributions link `/etc/environment` in as `99-environment.conf`,
468
+ which sorts *after* `99-env.conf`, so for any name set in both (often
469
+ `EDITOR`, `VISUAL`) the systemd session uses `/etc/environment`'s value
470
+ from the next login on. Until then, the running session has syncdot's
471
+ value, since syncdot pushes changes into it directly. Shells that source
472
+ the hook always get syncdot's value.
473
+ - `99-env.conf` belongs to syncdot: don't edit it, and if you track
474
+ `~/.config/environment.d` itself, syncdot leaves this file out of the
475
+ repo.
476
+ - Like everything in `vars.yaml`, env variables are per profile.
477
+ - Shells that are already open keep their old environment; open a new one
478
+ (or re-run the hook line) to pick up changes. Graphical sessions pick up
479
+ `environment.d` changes at the next login.
480
+
481
+ ## Conflicts
482
+
483
+ A conflict means a file changed both on disk and in the repo since it was
484
+ last synced on this machine. (A file that was never synced on this machine
485
+ isn't a conflict: `sync` leaves it alone until you `pull` or `push` it.)
486
+ `conflict_resolution` in the config decides what happens:
487
+
488
+ | Mode | Behaviour |
489
+ | --- | --- |
490
+ | `local-wins` (default) | This machine's version wins and is pushed. |
491
+ | `newer-wins` | The newer side wins: the file's modification time on disk vs the time of the last commit that changed it in the repo. |
492
+ | `repo-wins` | The repo's version wins and overwrites the local file. |
493
+
494
+ (Before 0.8.0 these were `machine-wins`, `last-write-wins` and `git-wins`;
495
+ the old names still work.)
496
+
497
+ `local-wins` is the default because it never loses anything: the repo's
498
+ version it replaces stays in git history, while a local file that gets
499
+ overwritten is gone. The sync output shows where to find it:
500
+
501
+ ```
502
+ ! ~/.vimrc [local-wins; repo version kept in history at 3f2c1ab]
503
+ ```
504
+ ```sh
505
+ git -C ~/.local/share/syncdot/repo show 3f2c1ab:files/.vimrc # view it
506
+ syncdot push ~/.vimrc # after restoring the file
507
+ ```
508
+
509
+ `syncdot push` and `syncdot pull` are one-off overrides equivalent to
510
+ `local-wins` and `repo-wins` (and `pull` asks before overwriting local
511
+ changes).
512
+
513
+ ## Configuration
514
+
515
+ `~/.config/syncdot/config.yaml` (override the location with the
516
+ `SYNCDOT_CONFIG` environment variable):
517
+
518
+ ```yaml
519
+ profile: base # active profile
520
+ conflict_resolution: local-wins # or newer-wins / repo-wins
521
+ auto_push: true # push to GitHub after each commit
522
+ include_binary: false # sync binary files too
523
+ repo_path: ~/.local/share/syncdot/repo
524
+ state_path: ~/.local/state/syncdot/state.json
525
+ ```
526
+
527
+ ## What is not synced
528
+
529
+ - **Binary files** (a NUL byte in the first 8 KB) are skipped unless
530
+ `include_binary: true`.
531
+ - **Symlinks** are never tracked or followed; inside a tracked directory
532
+ they are left untouched on both sides.
533
+ - **Nested `.git` directories** inside a tracked directory are ignored, so
534
+ they don't turn into submodules.
535
+ - **Private files** (e.g. mode `600`) are refused by `add` unless you pass
536
+ `--allow-private`.
537
+ - **Permissions**, apart from the executable bit: git records only whether
538
+ a file is executable, so pulled files get your default permissions
539
+ (usually `644`, or `755` for executables). A file tracked with
540
+ `--allow-private` is therefore *not* kept at `600` on other machines. A
541
+ change to the executable bit alone, with no content change, isn't synced.
542
+
543
+ ## Development
544
+
545
+ ```sh
546
+ python -m venv .venv
547
+ .venv/bin/pip install -e '.[dev]'
548
+ .venv/bin/pytest
549
+ ```
550
+
551
+ Each test runs the real CLI in an isolated sandbox: a bare git repo standing
552
+ in for GitHub, a temporary home directory and config, and a fake
553
+ `systemctl` that only records its arguments. Tests never touch your real
554
+ files, dotfiles repo or systemd session. The suite runs on every push and
555
+ pull request (`.github/workflows/tests.yml`).
556
+
557
+ ## Changelog
558
+
559
+ See [CHANGELOG.md](CHANGELOG.md). syncdot is pre-1.0: minor releases may
560
+ include breaking changes, which are always called out there.
561
+
562
+ ## License
563
+
564
+ Copyright (c) 2026 Ariel Shatil. syncdot is released under the
565
+ [MIT License](LICENSE). (Versions up to 0.8.0 were released under the GPL
566
+ 3.0 or later.)
567
+
568
+ ## How it works
569
+
570
+ Three places are involved: your files on disk, a local clone of your
571
+ dotfiles repo, and GitHub. A machine-local state file records the hash of
572
+ what was last synced for each file, which is how syncdot tells which side
573
+ changed. Templates (`.j2`) are rendered on the way to disk.
574
+
575
+ ```mermaid
576
+ %%{init: {"flowchart": {"nodeSpacing": 18, "rankSpacing": 28, "padding": 6, "diagramPadding": 4}}}%%
577
+ flowchart LR
578
+ state["state.json<br/>last-synced hashes"]
579
+ disk["Disk<br/>~/.vimrc …"]
580
+ clone["Local clone<br/>~/.local/share/syncdot/repo"]
581
+ gh[("GitHub")]
582
+ state -.- disk
583
+ disk -- "push / add" --> clone
584
+ clone -- "pull / checkout" --> disk
585
+ clone -- "git push" --> gh
586
+ gh -- "git pull" --> clone
587
+ ```
588
+
589
+ ### What `syncdot sync` does
590
+
591
+ On a profile other than `base`, sync first merges `base` into the
592
+ profile branch. It then decides each file as below, commits and pushes if
593
+ anything in the repo changed (plain pushes or conflicts the disk won), and
594
+ saves the state file.
595
+
596
+ ```mermaid
597
+ %%{init: {"flowchart": {"nodeSpacing": 18, "rankSpacing": 28, "padding": 6, "diagramPadding": 4}}}%%
598
+ flowchart LR
599
+ start(["sync"]) --> pull["git pull<br/>profile branch"]
600
+ pull --> merge["merge base in<br/>(profiles only)"]
601
+ merge --> each["each file:<br/>decide + act"]
602
+ each --> commit["commit + push<br/>if repo changed"]
603
+ commit --> save(["save state"])
604
+ ```
605
+
606
+ ### How each file is decided
607
+
608
+ For every tracked file syncdot computes three hashes: the file on disk, the
609
+ file in the repo (after rendering templates), and the one it recorded the
610
+ last time it synced that file.
611
+
612
+ ```mermaid
613
+ %%{init: {"flowchart": {"nodeSpacing": 18, "rankSpacing": 28, "padding": 6, "diagramPadding": 4}}}%%
614
+ flowchart LR
615
+ f(["file"]) --> known{"synced<br/>before?"}
616
+ known -- no --> samenew{"disk =<br/>repo?"}
617
+ samenew -- yes --> recnew["· record"]
618
+ samenew -- no --> wait["- skip until<br/>pull / push"]
619
+ known -- yes --> changed{"changed<br/>since?"}
620
+ changed -- neither --> nothing["· in sync"]
621
+ changed -- disk --> push["↑ push"]
622
+ changed -- repo --> pull["↓ pull"]
623
+ changed -- both --> same{"disk =<br/>repo?"}
624
+ same -- yes --> rec["· record"]
625
+ same -- no --> conf["! conflict"]
626
+ ```
627
+
628
+ *record*: nothing to copy, just remember the hash. *skip*: a file never
629
+ synced on this machine (missing here, or different) is left alone until you
630
+ `pull` or `push` it. *conflict*: settled by `conflict_resolution` (default
631
+ `local-wins`; see [Conflicts](#conflicts)).
632
+
633
+ <details>
634
+ <summary>syncdot in ASCII, for terminals and plain text</summary>
635
+
636
+ ```text
637
+ oo oo
638
+ oo oo
639
+ oooooooo oo oo oo oooo oooooooo oooooooo oooooo oooooooooo
640
+ oo oo oo oooo oo oo oo oo oo oo oo
641
+ oooooo oo oo oo oo oo oo oo oo oo oo
642
+ oo oo oo oo oo oo oo oo oo oo oo
643
+ oooooooo oooooooo oo oo oooooooo oooooooo oooooo oooo
644
+ oo
645
+ oooooooo
646
+ ```
647
+
648
+ </details>