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 +22 -0
- syncdot-1.0.0/PKG-INFO +648 -0
- syncdot-1.0.0/README.md +614 -0
- syncdot-1.0.0/pyproject.toml +55 -0
- syncdot-1.0.0/setup.cfg +4 -0
- syncdot-1.0.0/syncdot/__init__.py +1 -0
- syncdot-1.0.0/syncdot/__main__.py +768 -0
- syncdot-1.0.0/syncdot/config.py +82 -0
- syncdot-1.0.0/syncdot/lock.py +61 -0
- syncdot-1.0.0/syncdot/migrate.py +74 -0
- syncdot-1.0.0/syncdot/renderer.py +138 -0
- syncdot-1.0.0/syncdot/repo.py +262 -0
- syncdot-1.0.0/syncdot/state.py +159 -0
- syncdot-1.0.0/syncdot/sync.py +1349 -0
- syncdot-1.0.0/syncdot/systemd.py +108 -0
- syncdot-1.0.0/syncdot.egg-info/PKG-INFO +648 -0
- syncdot-1.0.0/syncdot.egg-info/SOURCES.txt +30 -0
- syncdot-1.0.0/syncdot.egg-info/dependency_links.txt +1 -0
- syncdot-1.0.0/syncdot.egg-info/entry_points.txt +2 -0
- syncdot-1.0.0/syncdot.egg-info/requires.txt +8 -0
- syncdot-1.0.0/syncdot.egg-info/top_level.txt +1 -0
- syncdot-1.0.0/tests/test_dry_run_and_lock.py +161 -0
- syncdot-1.0.0/tests/test_helpers.py +91 -0
- syncdot-1.0.0/tests/test_install_service.py +210 -0
- syncdot-1.0.0/tests/test_migrate.py +83 -0
- syncdot-1.0.0/tests/test_new_machine.py +101 -0
- syncdot-1.0.0/tests/test_profiles_templates.py +103 -0
- syncdot-1.0.0/tests/test_review_0_8.py +241 -0
- syncdot-1.0.0/tests/test_status.py +100 -0
- syncdot-1.0.0/tests/test_sync.py +255 -0
- syncdot-1.0.0/tests/test_tracking.py +135 -0
- syncdot-1.0.0/tests/test_vars_env.py +174 -0
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>
|