dotctl 1.0.8__tar.gz → 1.1.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.
- {dotctl-1.0.8/src/dotctl.egg-info → dotctl-1.1.0}/PKG-INFO +114 -19
- {dotctl-1.0.8 → dotctl-1.1.0}/README.md +111 -18
- {dotctl-1.0.8 → dotctl-1.1.0}/pyproject.toml +3 -3
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/__init__.py +1 -1
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/activator.py +5 -2
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/creator.py +16 -24
- dotctl-1.1.0/src/dotctl/actions/differ.py +108 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/exporter.py +12 -1
- dotctl-1.1.0/src/dotctl/actions/importer.py +180 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/remover.py +2 -1
- dotctl-1.1.0/src/dotctl/actions/saver.py +201 -0
- dotctl-1.1.0/src/dotctl/actions/status.py +442 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/arg_manager.py +43 -1
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/exception.py +3 -1
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/handlers/config_handler.py +26 -4
- dotctl-1.1.0/src/dotctl/handlers/data_handler.py +245 -0
- dotctl-1.1.0/src/dotctl/handlers/diff_handler.py +242 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/handlers/git_handler.py +3 -9
- dotctl-1.1.0/src/dotctl/handlers/status_handler.py +205 -0
- dotctl-1.1.0/src/dotctl/handlers/sudo_handler.py +283 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/main.py +38 -3
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/templates/kde.yaml +3 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/utils.py +1 -1
- {dotctl-1.0.8 → dotctl-1.1.0/src/dotctl.egg-info}/PKG-INFO +114 -19
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl.egg-info/SOURCES.txt +5 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl.egg-info/requires.txt +1 -0
- dotctl-1.0.8/src/dotctl/actions/importer.py +0 -133
- dotctl-1.0.8/src/dotctl/actions/saver.py +0 -100
- dotctl-1.0.8/src/dotctl/handlers/data_handler.py +0 -142
- {dotctl-1.0.8 → dotctl-1.1.0}/LICENSE +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/setup.cfg +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/__init__.py +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/initializer.py +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/lister.py +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/puller.py +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/switcher.py +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/wiper.py +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/handlers/__init__.py +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/handlers/hooks_handler.py +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/hooks/post_apply.sh +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/hooks/pre_apply.sh +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/paths.py +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/templates/__init__.py +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/templates/dev.yaml +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/templates/other.yaml +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/validators.py +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl.egg-info/dependency_links.txt +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl.egg-info/entry_points.txt +0 -0
- {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl.egg-info/top_level.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: dotctl
|
|
3
|
-
Version: 1.0
|
|
3
|
+
Version: 1.1.0
|
|
4
4
|
Summary: A powerful CLI tool to profile your OS by saving, applying, exporting, and importing system configurations as named profiles. Designed to manage dot files and service configurations in a centralized Git repository (local or remote), dotctl enables seamless system replication across machines. Supports pre/post hook scripts, making it ideal for setting up servers or desktops with consistent environments.
|
|
5
5
|
Author-email: Pankaj Jackson <pankajackson@live.co.uk>
|
|
6
6
|
License-Expression: MIT
|
|
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.12
|
|
|
14
14
|
Classifier: Programming Language :: Python :: 3.13
|
|
15
15
|
Classifier: Development Status :: 4 - Beta
|
|
16
16
|
Classifier: Intended Audience :: End Users/Desktop
|
|
17
|
+
Classifier: Operating System :: MacOS
|
|
17
18
|
Classifier: Operating System :: POSIX :: Linux
|
|
18
19
|
Classifier: Topic :: System :: Archiving :: Backup
|
|
19
20
|
Classifier: Topic :: Utilities
|
|
@@ -22,6 +23,7 @@ Description-Content-Type: text/markdown
|
|
|
22
23
|
License-File: LICENSE
|
|
23
24
|
Requires-Dist: PyYAML
|
|
24
25
|
Requires-Dist: gitpython
|
|
26
|
+
Requires-Dist: rich
|
|
25
27
|
Dynamic: license-file
|
|
26
28
|
|
|
27
29
|
# DotCtl
|
|
@@ -57,9 +59,13 @@ Designed for developers and sysadmins, it supports pre/post hook scripts and is
|
|
|
57
59
|
- [🆕 `create` / `new`](#-create--new)
|
|
58
60
|
- [❌ `remove` / `rm` / `delete` / `del`](#-remove--rm--delete--del)
|
|
59
61
|
- [🧪 `apply`](#-apply)
|
|
62
|
+
- [🔄 `pull`](#-pull)
|
|
63
|
+
- [🔍 `status`](#-status)
|
|
64
|
+
- [🔎 `diff`](#-diff)
|
|
60
65
|
- [📤 `export`](#-export)
|
|
61
66
|
- [📥 `import`](#-import)
|
|
62
67
|
- [🔥 `wipe`](#-wipe)
|
|
68
|
+
- [⚠️ Limitations \& Notes](#️-limitations--notes)
|
|
63
69
|
- [🧑💻 Development \& Publishing](#-development--publishing)
|
|
64
70
|
- [Setup Development Environment](#setup-development-environment)
|
|
65
71
|
- [Test the new code](#test-the-new-code)
|
|
@@ -77,12 +83,13 @@ Designed for developers and sysadmins, it supports pre/post hook scripts and is
|
|
|
77
83
|
- 🔄 **Git Integration** — Sync profiles with local or remote Git repositories.
|
|
78
84
|
- 📁 **Portable Configs** — Export/import profiles using `.dtsv` files for easy backups and sharing.
|
|
79
85
|
- ⚙️ **Custom Configs** — Define tracking rules via `dotctl.yaml`.
|
|
86
|
+
- 🧹 **Prune Support** — Clean stale files no longer listed in your profile with --prune.
|
|
80
87
|
|
|
81
88
|
---
|
|
82
89
|
|
|
83
90
|
## 📁 Profile Config Structure (`dotctl.yaml`)
|
|
84
91
|
|
|
85
|
-
The `dotctl.
|
|
92
|
+
The `dotctl.yaml` config file defines what files and directories to **track**, **save**, and **export** as part of a system profile. This enables seamless migration, sharing, and restoration of system configs and personalizations—perfect for dotfiles, apps, or entire setups like KDE.
|
|
86
93
|
|
|
87
94
|
### 🧠 Concept Overview
|
|
88
95
|
|
|
@@ -116,6 +123,11 @@ To simplify path definitions, these keys can be used in `location`:
|
|
|
116
123
|
|
|
117
124
|
Use them to make profiles portable across systems.
|
|
118
125
|
|
|
126
|
+
Each `save` or `export` section may set `required_sudo: true` when its configured
|
|
127
|
+
location should be accessed through sudo. If `sudo` is omitted or `false`,
|
|
128
|
+
dotctl first uses normal access and asks for sudo only if the path is restricted.
|
|
129
|
+
At the prompt, you can provide a password or skip the current path/all paths.
|
|
130
|
+
|
|
119
131
|
---
|
|
120
132
|
|
|
121
133
|
### ✅ Example: Minimal Config
|
|
@@ -234,6 +246,7 @@ export:
|
|
|
234
246
|
|
|
235
247
|
sddm:
|
|
236
248
|
location: $SYS_SHARE_DIR/sddm
|
|
249
|
+
required_sudo: true
|
|
237
250
|
entries:
|
|
238
251
|
- themes
|
|
239
252
|
```
|
|
@@ -258,7 +271,7 @@ This diagram shows the typical lifecycle of using a `dotctl` profile, from savin
|
|
|
258
271
|
|
|
259
272
|
```js
|
|
260
273
|
┌──────────────┐
|
|
261
|
-
│
|
|
274
|
+
│ dotctl.yaml │
|
|
262
275
|
└──────┬───────┘
|
|
263
276
|
│
|
|
264
277
|
┌─────────▼──────────┐
|
|
@@ -310,12 +323,14 @@ This diagram shows the typical lifecycle of using a `dotctl` profile, from savin
|
|
|
310
323
|
|
|
311
324
|
## 📊 Profile Block Table
|
|
312
325
|
|
|
313
|
-
| Section | Field
|
|
314
|
-
| -------- |
|
|
315
|
-
| `save` | `location`
|
|
316
|
-
| | `entries`
|
|
317
|
-
|
|
|
318
|
-
|
|
|
326
|
+
| Section | Field | Description |
|
|
327
|
+
| -------- | --------------- | ----------------------------------------------------------------- |
|
|
328
|
+
| `save` | `location` | Base path of tracked files (can use a key like `$CONFIG_DIR`) |
|
|
329
|
+
| | `entries` | Files/folders to track under that location |
|
|
330
|
+
| | `required_sudo` | Whether restricted paths in this section require sudo |
|
|
331
|
+
| `export` | `location` | Base path of export files (e.g., large assets not suited for Git) |
|
|
332
|
+
| | `entries` | Assets or binaries to package in `.dtsv` |
|
|
333
|
+
| | `required_sudo` | Whether restricted paths in this section require sudo |
|
|
319
334
|
|
|
320
335
|
---
|
|
321
336
|
|
|
@@ -323,7 +338,7 @@ This diagram shows the typical lifecycle of using a `dotctl` profile, from savin
|
|
|
323
338
|
|
|
324
339
|
| Action | Command | Description |
|
|
325
340
|
| --------------- | ---------------------- | ----------------------------------------------------------- |
|
|
326
|
-
| Save configs | `dotctl save` |
|
|
341
|
+
| Save configs | `dotctl save` | Saves configured files to the active profile and syncs Git |
|
|
327
342
|
| Export assets | `dotctl export` | Package large, non-Git assets into `.dtsv` file |
|
|
328
343
|
| Transfer assets | `scp profile.dtsv ...` | Manually copy to another machine |
|
|
329
344
|
| Import assets | `dotctl import` | Unpack `.dtsv` on another system |
|
|
@@ -337,6 +352,9 @@ This diagram shows the typical lifecycle of using a `dotctl` profile, from savin
|
|
|
337
352
|
pip install dotctl
|
|
338
353
|
```
|
|
339
354
|
|
|
355
|
+
Profile operations require the `git` command. Commands that copy files also require
|
|
356
|
+
`rsync`. Restricted paths prompt for a sudo password when needed.
|
|
357
|
+
|
|
340
358
|
---
|
|
341
359
|
|
|
342
360
|
## 📘 Usage
|
|
@@ -378,10 +396,10 @@ dotctl init -c ./my_custom_config.yaml
|
|
|
378
396
|
|
|
379
397
|
### 💾 `save`
|
|
380
398
|
|
|
381
|
-
Save current system state to
|
|
399
|
+
Save current system state to a profile.
|
|
382
400
|
|
|
383
401
|
```sh
|
|
384
|
-
dotctl save [-h] [-p <password>] [--skip-sudo] [profile]
|
|
402
|
+
dotctl save [-h] [-p <password>] [--skip-sudo] [--prune] [profile]
|
|
385
403
|
```
|
|
386
404
|
|
|
387
405
|
**Examples:**
|
|
@@ -389,13 +407,28 @@ dotctl save [-h] [-p <password>] [--skip-sudo] [profile]
|
|
|
389
407
|
```sh
|
|
390
408
|
dotctl save
|
|
391
409
|
dotctl save my_web_server --skip-sudo
|
|
392
|
-
dotctl save
|
|
410
|
+
dotctl save --prune
|
|
411
|
+
dotctl save a_new_profile
|
|
393
412
|
```
|
|
394
413
|
|
|
414
|
+
Without a profile name, `save` targets the active profile. If the named profile
|
|
415
|
+
already exists, dotctl saves to it and then returns to the previously active
|
|
416
|
+
profile. If it does not exist, dotctl creates it from the active profile, saves
|
|
417
|
+
the current system state there, and returns to the previous profile. When a
|
|
418
|
+
remote is configured, dotctl pushes a target branch that is not on the remote,
|
|
419
|
+
even if the save produced no file changes.
|
|
420
|
+
|
|
421
|
+
Prefer the interactive sudo prompt over passing a password with `-p`, since command-line
|
|
422
|
+
arguments can be recorded in shell history or visible to other local processes.
|
|
423
|
+
|
|
424
|
+
> Tip: Use --prune to clean files that were saved before but are no longer listed in the config.
|
|
425
|
+
|
|
395
426
|
**Options:**
|
|
396
427
|
|
|
397
428
|
- `--skip-sudo` – Ignore restricted resources.
|
|
398
429
|
- `-p, --password` – Password for restricted resources.
|
|
430
|
+
- `--prune` – Remove stale files from the dot repo that are no longer listed in the current `dotctl.yaml` config.
|
|
431
|
+
- `profile` – Target profile. A new name starts as a copy of the active profile; omitted means the active profile.
|
|
399
432
|
|
|
400
433
|
---
|
|
401
434
|
|
|
@@ -445,7 +478,8 @@ dotctl sw MyProfile --fetch
|
|
|
445
478
|
|
|
446
479
|
### 🆕 `create` / `new`
|
|
447
480
|
|
|
448
|
-
Create a new, empty profile.
|
|
481
|
+
Create a new, empty profile and initialize its config and hooks. The new profile
|
|
482
|
+
becomes active.
|
|
449
483
|
|
|
450
484
|
```sh
|
|
451
485
|
dotctl create [-h] [--fetch] [-c <path>] [-e <env>] profile
|
|
@@ -454,14 +488,14 @@ dotctl create [-h] [--fetch] [-c <path>] [-e <env>] profile
|
|
|
454
488
|
**Examples:**
|
|
455
489
|
|
|
456
490
|
```sh
|
|
457
|
-
# Create a
|
|
491
|
+
# Create a fresh profile using the detected environment or default config.
|
|
458
492
|
dotctl create myserver
|
|
459
493
|
|
|
460
|
-
# Create a
|
|
461
|
-
dotctl create -e kde
|
|
494
|
+
# Create a fresh profile from a specific environment.
|
|
495
|
+
dotctl create -e kde kde_desktop
|
|
462
496
|
|
|
463
|
-
# Create a
|
|
464
|
-
dotctl create -c ./my_custom_config.yaml
|
|
497
|
+
# Create a fresh profile from a custom config.
|
|
498
|
+
dotctl create -c ./my_custom_config.yaml my_custom_profile
|
|
465
499
|
```
|
|
466
500
|
|
|
467
501
|
**Options:**
|
|
@@ -524,6 +558,58 @@ dotctl apply MyProfile --skip-pre-hooks --ignore-hook-errors
|
|
|
524
558
|
|
|
525
559
|
---
|
|
526
560
|
|
|
561
|
+
### 🔄 `pull`
|
|
562
|
+
|
|
563
|
+
Pull the latest changes from the dotfiles repository.
|
|
564
|
+
|
|
565
|
+
```sh
|
|
566
|
+
dotctl pull [-h]
|
|
567
|
+
```
|
|
568
|
+
|
|
569
|
+
**Examples:**
|
|
570
|
+
|
|
571
|
+
```sh
|
|
572
|
+
dotctl pull
|
|
573
|
+
```
|
|
574
|
+
|
|
575
|
+
---
|
|
576
|
+
|
|
577
|
+
### 🔍 `status`
|
|
578
|
+
|
|
579
|
+
Inspect the current profile health and detect configuration drift between the repository and local system.
|
|
580
|
+
|
|
581
|
+
```sh
|
|
582
|
+
dotctl status [--json] [--short]
|
|
583
|
+
```
|
|
584
|
+
|
|
585
|
+
**Examples:**
|
|
586
|
+
|
|
587
|
+
```sh
|
|
588
|
+
dotctl status
|
|
589
|
+
dotctl status --short
|
|
590
|
+
dotctl status --json
|
|
591
|
+
```
|
|
592
|
+
|
|
593
|
+
---
|
|
594
|
+
|
|
595
|
+
### 🔎 `diff`
|
|
596
|
+
|
|
597
|
+
Compare tracked files between the repository and local system.
|
|
598
|
+
|
|
599
|
+
```sh
|
|
600
|
+
dotctl diff [--color] [--side-by-side]
|
|
601
|
+
```
|
|
602
|
+
|
|
603
|
+
**Examples:**
|
|
604
|
+
|
|
605
|
+
```sh
|
|
606
|
+
dotctl diff
|
|
607
|
+
dotctl diff --color
|
|
608
|
+
dotctl diff --side-by-side
|
|
609
|
+
```
|
|
610
|
+
|
|
611
|
+
---
|
|
612
|
+
|
|
527
613
|
### 📤 `export`
|
|
528
614
|
|
|
529
615
|
Export a profile to `.dtsv`.
|
|
@@ -588,6 +674,15 @@ dotctl wipe -y
|
|
|
588
674
|
|
|
589
675
|
---
|
|
590
676
|
|
|
677
|
+
## ⚠️ Limitations & Notes
|
|
678
|
+
|
|
679
|
+
- Configured filesystem operations (`save`, `apply`, `export`, `import`, `status`, and `diff`) support sudo access for restricted paths. Set `required_sudo: true` on the relevant config section when sudo access is expected; otherwise dotctl tries normal access and requests sudo if needed.
|
|
680
|
+
- `status` and `diff` can report paths as inaccessible when access is denied or the user skips the sudo request.
|
|
681
|
+
- Ensure tracked files/directories have proper read permissions before adding them to `dotctl.yaml`.
|
|
682
|
+
- Missing or inaccessible files may appear as drift during `status` or `diff` operations.
|
|
683
|
+
|
|
684
|
+
---
|
|
685
|
+
|
|
591
686
|
## 🧑💻 Development & Publishing
|
|
592
687
|
|
|
593
688
|
### Setup Development Environment
|
|
@@ -31,9 +31,13 @@ Designed for developers and sysadmins, it supports pre/post hook scripts and is
|
|
|
31
31
|
- [🆕 `create` / `new`](#-create--new)
|
|
32
32
|
- [❌ `remove` / `rm` / `delete` / `del`](#-remove--rm--delete--del)
|
|
33
33
|
- [🧪 `apply`](#-apply)
|
|
34
|
+
- [🔄 `pull`](#-pull)
|
|
35
|
+
- [🔍 `status`](#-status)
|
|
36
|
+
- [🔎 `diff`](#-diff)
|
|
34
37
|
- [📤 `export`](#-export)
|
|
35
38
|
- [📥 `import`](#-import)
|
|
36
39
|
- [🔥 `wipe`](#-wipe)
|
|
40
|
+
- [⚠️ Limitations \& Notes](#️-limitations--notes)
|
|
37
41
|
- [🧑💻 Development \& Publishing](#-development--publishing)
|
|
38
42
|
- [Setup Development Environment](#setup-development-environment)
|
|
39
43
|
- [Test the new code](#test-the-new-code)
|
|
@@ -51,12 +55,13 @@ Designed for developers and sysadmins, it supports pre/post hook scripts and is
|
|
|
51
55
|
- 🔄 **Git Integration** — Sync profiles with local or remote Git repositories.
|
|
52
56
|
- 📁 **Portable Configs** — Export/import profiles using `.dtsv` files for easy backups and sharing.
|
|
53
57
|
- ⚙️ **Custom Configs** — Define tracking rules via `dotctl.yaml`.
|
|
58
|
+
- 🧹 **Prune Support** — Clean stale files no longer listed in your profile with --prune.
|
|
54
59
|
|
|
55
60
|
---
|
|
56
61
|
|
|
57
62
|
## 📁 Profile Config Structure (`dotctl.yaml`)
|
|
58
63
|
|
|
59
|
-
The `dotctl.
|
|
64
|
+
The `dotctl.yaml` config file defines what files and directories to **track**, **save**, and **export** as part of a system profile. This enables seamless migration, sharing, and restoration of system configs and personalizations—perfect for dotfiles, apps, or entire setups like KDE.
|
|
60
65
|
|
|
61
66
|
### 🧠 Concept Overview
|
|
62
67
|
|
|
@@ -90,6 +95,11 @@ To simplify path definitions, these keys can be used in `location`:
|
|
|
90
95
|
|
|
91
96
|
Use them to make profiles portable across systems.
|
|
92
97
|
|
|
98
|
+
Each `save` or `export` section may set `required_sudo: true` when its configured
|
|
99
|
+
location should be accessed through sudo. If `sudo` is omitted or `false`,
|
|
100
|
+
dotctl first uses normal access and asks for sudo only if the path is restricted.
|
|
101
|
+
At the prompt, you can provide a password or skip the current path/all paths.
|
|
102
|
+
|
|
93
103
|
---
|
|
94
104
|
|
|
95
105
|
### ✅ Example: Minimal Config
|
|
@@ -208,6 +218,7 @@ export:
|
|
|
208
218
|
|
|
209
219
|
sddm:
|
|
210
220
|
location: $SYS_SHARE_DIR/sddm
|
|
221
|
+
required_sudo: true
|
|
211
222
|
entries:
|
|
212
223
|
- themes
|
|
213
224
|
```
|
|
@@ -232,7 +243,7 @@ This diagram shows the typical lifecycle of using a `dotctl` profile, from savin
|
|
|
232
243
|
|
|
233
244
|
```js
|
|
234
245
|
┌──────────────┐
|
|
235
|
-
│
|
|
246
|
+
│ dotctl.yaml │
|
|
236
247
|
└──────┬───────┘
|
|
237
248
|
│
|
|
238
249
|
┌─────────▼──────────┐
|
|
@@ -284,12 +295,14 @@ This diagram shows the typical lifecycle of using a `dotctl` profile, from savin
|
|
|
284
295
|
|
|
285
296
|
## 📊 Profile Block Table
|
|
286
297
|
|
|
287
|
-
| Section | Field
|
|
288
|
-
| -------- |
|
|
289
|
-
| `save` | `location`
|
|
290
|
-
| | `entries`
|
|
291
|
-
|
|
|
292
|
-
|
|
|
298
|
+
| Section | Field | Description |
|
|
299
|
+
| -------- | --------------- | ----------------------------------------------------------------- |
|
|
300
|
+
| `save` | `location` | Base path of tracked files (can use a key like `$CONFIG_DIR`) |
|
|
301
|
+
| | `entries` | Files/folders to track under that location |
|
|
302
|
+
| | `required_sudo` | Whether restricted paths in this section require sudo |
|
|
303
|
+
| `export` | `location` | Base path of export files (e.g., large assets not suited for Git) |
|
|
304
|
+
| | `entries` | Assets or binaries to package in `.dtsv` |
|
|
305
|
+
| | `required_sudo` | Whether restricted paths in this section require sudo |
|
|
293
306
|
|
|
294
307
|
---
|
|
295
308
|
|
|
@@ -297,7 +310,7 @@ This diagram shows the typical lifecycle of using a `dotctl` profile, from savin
|
|
|
297
310
|
|
|
298
311
|
| Action | Command | Description |
|
|
299
312
|
| --------------- | ---------------------- | ----------------------------------------------------------- |
|
|
300
|
-
| Save configs | `dotctl save` |
|
|
313
|
+
| Save configs | `dotctl save` | Saves configured files to the active profile and syncs Git |
|
|
301
314
|
| Export assets | `dotctl export` | Package large, non-Git assets into `.dtsv` file |
|
|
302
315
|
| Transfer assets | `scp profile.dtsv ...` | Manually copy to another machine |
|
|
303
316
|
| Import assets | `dotctl import` | Unpack `.dtsv` on another system |
|
|
@@ -311,6 +324,9 @@ This diagram shows the typical lifecycle of using a `dotctl` profile, from savin
|
|
|
311
324
|
pip install dotctl
|
|
312
325
|
```
|
|
313
326
|
|
|
327
|
+
Profile operations require the `git` command. Commands that copy files also require
|
|
328
|
+
`rsync`. Restricted paths prompt for a sudo password when needed.
|
|
329
|
+
|
|
314
330
|
---
|
|
315
331
|
|
|
316
332
|
## 📘 Usage
|
|
@@ -352,10 +368,10 @@ dotctl init -c ./my_custom_config.yaml
|
|
|
352
368
|
|
|
353
369
|
### 💾 `save`
|
|
354
370
|
|
|
355
|
-
Save current system state to
|
|
371
|
+
Save current system state to a profile.
|
|
356
372
|
|
|
357
373
|
```sh
|
|
358
|
-
dotctl save [-h] [-p <password>] [--skip-sudo] [profile]
|
|
374
|
+
dotctl save [-h] [-p <password>] [--skip-sudo] [--prune] [profile]
|
|
359
375
|
```
|
|
360
376
|
|
|
361
377
|
**Examples:**
|
|
@@ -363,13 +379,28 @@ dotctl save [-h] [-p <password>] [--skip-sudo] [profile]
|
|
|
363
379
|
```sh
|
|
364
380
|
dotctl save
|
|
365
381
|
dotctl save my_web_server --skip-sudo
|
|
366
|
-
dotctl save
|
|
382
|
+
dotctl save --prune
|
|
383
|
+
dotctl save a_new_profile
|
|
367
384
|
```
|
|
368
385
|
|
|
386
|
+
Without a profile name, `save` targets the active profile. If the named profile
|
|
387
|
+
already exists, dotctl saves to it and then returns to the previously active
|
|
388
|
+
profile. If it does not exist, dotctl creates it from the active profile, saves
|
|
389
|
+
the current system state there, and returns to the previous profile. When a
|
|
390
|
+
remote is configured, dotctl pushes a target branch that is not on the remote,
|
|
391
|
+
even if the save produced no file changes.
|
|
392
|
+
|
|
393
|
+
Prefer the interactive sudo prompt over passing a password with `-p`, since command-line
|
|
394
|
+
arguments can be recorded in shell history or visible to other local processes.
|
|
395
|
+
|
|
396
|
+
> Tip: Use --prune to clean files that were saved before but are no longer listed in the config.
|
|
397
|
+
|
|
369
398
|
**Options:**
|
|
370
399
|
|
|
371
400
|
- `--skip-sudo` – Ignore restricted resources.
|
|
372
401
|
- `-p, --password` – Password for restricted resources.
|
|
402
|
+
- `--prune` – Remove stale files from the dot repo that are no longer listed in the current `dotctl.yaml` config.
|
|
403
|
+
- `profile` – Target profile. A new name starts as a copy of the active profile; omitted means the active profile.
|
|
373
404
|
|
|
374
405
|
---
|
|
375
406
|
|
|
@@ -419,7 +450,8 @@ dotctl sw MyProfile --fetch
|
|
|
419
450
|
|
|
420
451
|
### 🆕 `create` / `new`
|
|
421
452
|
|
|
422
|
-
Create a new, empty profile.
|
|
453
|
+
Create a new, empty profile and initialize its config and hooks. The new profile
|
|
454
|
+
becomes active.
|
|
423
455
|
|
|
424
456
|
```sh
|
|
425
457
|
dotctl create [-h] [--fetch] [-c <path>] [-e <env>] profile
|
|
@@ -428,14 +460,14 @@ dotctl create [-h] [--fetch] [-c <path>] [-e <env>] profile
|
|
|
428
460
|
**Examples:**
|
|
429
461
|
|
|
430
462
|
```sh
|
|
431
|
-
# Create a
|
|
463
|
+
# Create a fresh profile using the detected environment or default config.
|
|
432
464
|
dotctl create myserver
|
|
433
465
|
|
|
434
|
-
# Create a
|
|
435
|
-
dotctl create -e kde
|
|
466
|
+
# Create a fresh profile from a specific environment.
|
|
467
|
+
dotctl create -e kde kde_desktop
|
|
436
468
|
|
|
437
|
-
# Create a
|
|
438
|
-
dotctl create -c ./my_custom_config.yaml
|
|
469
|
+
# Create a fresh profile from a custom config.
|
|
470
|
+
dotctl create -c ./my_custom_config.yaml my_custom_profile
|
|
439
471
|
```
|
|
440
472
|
|
|
441
473
|
**Options:**
|
|
@@ -498,6 +530,58 @@ dotctl apply MyProfile --skip-pre-hooks --ignore-hook-errors
|
|
|
498
530
|
|
|
499
531
|
---
|
|
500
532
|
|
|
533
|
+
### 🔄 `pull`
|
|
534
|
+
|
|
535
|
+
Pull the latest changes from the dotfiles repository.
|
|
536
|
+
|
|
537
|
+
```sh
|
|
538
|
+
dotctl pull [-h]
|
|
539
|
+
```
|
|
540
|
+
|
|
541
|
+
**Examples:**
|
|
542
|
+
|
|
543
|
+
```sh
|
|
544
|
+
dotctl pull
|
|
545
|
+
```
|
|
546
|
+
|
|
547
|
+
---
|
|
548
|
+
|
|
549
|
+
### 🔍 `status`
|
|
550
|
+
|
|
551
|
+
Inspect the current profile health and detect configuration drift between the repository and local system.
|
|
552
|
+
|
|
553
|
+
```sh
|
|
554
|
+
dotctl status [--json] [--short]
|
|
555
|
+
```
|
|
556
|
+
|
|
557
|
+
**Examples:**
|
|
558
|
+
|
|
559
|
+
```sh
|
|
560
|
+
dotctl status
|
|
561
|
+
dotctl status --short
|
|
562
|
+
dotctl status --json
|
|
563
|
+
```
|
|
564
|
+
|
|
565
|
+
---
|
|
566
|
+
|
|
567
|
+
### 🔎 `diff`
|
|
568
|
+
|
|
569
|
+
Compare tracked files between the repository and local system.
|
|
570
|
+
|
|
571
|
+
```sh
|
|
572
|
+
dotctl diff [--color] [--side-by-side]
|
|
573
|
+
```
|
|
574
|
+
|
|
575
|
+
**Examples:**
|
|
576
|
+
|
|
577
|
+
```sh
|
|
578
|
+
dotctl diff
|
|
579
|
+
dotctl diff --color
|
|
580
|
+
dotctl diff --side-by-side
|
|
581
|
+
```
|
|
582
|
+
|
|
583
|
+
---
|
|
584
|
+
|
|
501
585
|
### 📤 `export`
|
|
502
586
|
|
|
503
587
|
Export a profile to `.dtsv`.
|
|
@@ -562,6 +646,15 @@ dotctl wipe -y
|
|
|
562
646
|
|
|
563
647
|
---
|
|
564
648
|
|
|
649
|
+
## ⚠️ Limitations & Notes
|
|
650
|
+
|
|
651
|
+
- Configured filesystem operations (`save`, `apply`, `export`, `import`, `status`, and `diff`) support sudo access for restricted paths. Set `required_sudo: true` on the relevant config section when sudo access is expected; otherwise dotctl tries normal access and requests sudo if needed.
|
|
652
|
+
- `status` and `diff` can report paths as inaccessible when access is denied or the user skips the sudo request.
|
|
653
|
+
- Ensure tracked files/directories have proper read permissions before adding them to `dotctl.yaml`.
|
|
654
|
+
- Missing or inaccessible files may appear as drift during `status` or `diff` operations.
|
|
655
|
+
|
|
656
|
+
---
|
|
657
|
+
|
|
565
658
|
## 🧑💻 Development & Publishing
|
|
566
659
|
|
|
567
660
|
### Setup Development Environment
|
|
@@ -4,15 +4,15 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "dotctl"
|
|
7
|
-
version = "v1.0
|
|
7
|
+
version = "v1.1.0"
|
|
8
8
|
description = "A powerful CLI tool to profile your OS by saving, applying, exporting, and importing system configurations as named profiles. Designed to manage dot files and service configurations in a centralized Git repository (local or remote), dotctl enables seamless system replication across machines. Supports pre/post hook scripts, making it ideal for setting up servers or desktops with consistent environments."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
license = "MIT"
|
|
11
11
|
license-files = [ "LICENSE",]
|
|
12
12
|
requires-python = ">=3.10"
|
|
13
|
-
dependencies = [ "PyYAML", "gitpython",]
|
|
13
|
+
dependencies = [ "PyYAML", "gitpython", "rich",]
|
|
14
14
|
keywords = [ "dotfiles", "config", "settings", "backup", "dotfile-manager",]
|
|
15
|
-
classifiers = [ "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Development Status :: 4 - Beta", "Intended Audience :: End Users/Desktop", "Operating System :: POSIX :: Linux", "Topic :: System :: Archiving :: Backup", "Topic :: Utilities",]
|
|
15
|
+
classifiers = [ "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Development Status :: 4 - Beta", "Intended Audience :: End Users/Desktop", "Operating System :: MacOS", "Operating System :: POSIX :: Linux", "Topic :: System :: Archiving :: Backup", "Topic :: Utilities",]
|
|
16
16
|
[[project.authors]]
|
|
17
17
|
name = "Pankaj Jackson"
|
|
18
18
|
email = "pankajackson@live.co.uk"
|
|
@@ -72,13 +72,16 @@ def apply(props: ActivatorProps) -> None:
|
|
|
72
72
|
for name, section in config.save.items():
|
|
73
73
|
source_base_dir = profile_dir / name
|
|
74
74
|
dest_base_dir = Path(section.location)
|
|
75
|
-
dest_base_dir.mkdir(exist_ok=True)
|
|
76
75
|
log(f'Applying "{name}"...')
|
|
77
76
|
for entry in section.entries:
|
|
78
77
|
source = source_base_dir / entry
|
|
79
78
|
dest = dest_base_dir / entry
|
|
80
79
|
result = copy(
|
|
81
|
-
source,
|
|
80
|
+
source,
|
|
81
|
+
dest,
|
|
82
|
+
skip_sudo=props.skip_sudo,
|
|
83
|
+
sudo_pass=props.password,
|
|
84
|
+
required_sudo=section.required_sudo,
|
|
82
85
|
)
|
|
83
86
|
|
|
84
87
|
# Updated props
|
|
@@ -15,7 +15,6 @@ from dotctl.handlers.git_handler import (
|
|
|
15
15
|
get_repo,
|
|
16
16
|
get_repo_branches,
|
|
17
17
|
git_fetch,
|
|
18
|
-
create_branch,
|
|
19
18
|
create_empty_branch,
|
|
20
19
|
is_remote_repo,
|
|
21
20
|
is_repo_changed,
|
|
@@ -55,17 +54,13 @@ def create(props: CreatorProps):
|
|
|
55
54
|
if props.profile in all_profiles:
|
|
56
55
|
log(f"❌ Profile '{props.profile}' already exists.")
|
|
57
56
|
return
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
)
|
|
66
|
-
hooks_initializer()
|
|
67
|
-
else:
|
|
68
|
-
create_branch(repo, props.profile)
|
|
57
|
+
|
|
58
|
+
create_empty_branch(repo, props.profile)
|
|
59
|
+
|
|
60
|
+
if isinstance(props.config, str):
|
|
61
|
+
props.config = Path(props.config)
|
|
62
|
+
conf_initializer(env=props.env, custom_config=props.config)
|
|
63
|
+
hooks_initializer()
|
|
69
64
|
|
|
70
65
|
add_changes(repo=repo)
|
|
71
66
|
if is_repo_changed(repo=repo):
|
|
@@ -73,17 +68,14 @@ def create(props: CreatorProps):
|
|
|
73
68
|
timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
|
|
74
69
|
full_message = f"{hostname} | Profile Initialized | {timestamp}"
|
|
75
70
|
commit_changes(repo=repo, message=full_message)
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
push_new_branch(repo=repo)
|
|
86
|
-
else:
|
|
87
|
-
push_existing_branch(repo=repo)
|
|
71
|
+
|
|
72
|
+
is_remote, _ = is_remote_repo(repo=repo)
|
|
73
|
+
if is_remote:
|
|
74
|
+
git_fetch(repo=repo)
|
|
75
|
+
_, remote_profiles, _, _ = get_repo_branches(repo)
|
|
76
|
+
if props.profile not in remote_profiles:
|
|
77
|
+
push_new_branch(repo=repo)
|
|
78
|
+
else:
|
|
79
|
+
push_existing_branch(repo=repo)
|
|
88
80
|
|
|
89
81
|
log(f"✅ Profile '{props.profile}' created and activated successfully.")
|