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.
Files changed (49) hide show
  1. {dotctl-1.0.8/src/dotctl.egg-info → dotctl-1.1.0}/PKG-INFO +114 -19
  2. {dotctl-1.0.8 → dotctl-1.1.0}/README.md +111 -18
  3. {dotctl-1.0.8 → dotctl-1.1.0}/pyproject.toml +3 -3
  4. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/__init__.py +1 -1
  5. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/activator.py +5 -2
  6. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/creator.py +16 -24
  7. dotctl-1.1.0/src/dotctl/actions/differ.py +108 -0
  8. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/exporter.py +12 -1
  9. dotctl-1.1.0/src/dotctl/actions/importer.py +180 -0
  10. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/remover.py +2 -1
  11. dotctl-1.1.0/src/dotctl/actions/saver.py +201 -0
  12. dotctl-1.1.0/src/dotctl/actions/status.py +442 -0
  13. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/arg_manager.py +43 -1
  14. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/exception.py +3 -1
  15. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/handlers/config_handler.py +26 -4
  16. dotctl-1.1.0/src/dotctl/handlers/data_handler.py +245 -0
  17. dotctl-1.1.0/src/dotctl/handlers/diff_handler.py +242 -0
  18. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/handlers/git_handler.py +3 -9
  19. dotctl-1.1.0/src/dotctl/handlers/status_handler.py +205 -0
  20. dotctl-1.1.0/src/dotctl/handlers/sudo_handler.py +283 -0
  21. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/main.py +38 -3
  22. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/templates/kde.yaml +3 -0
  23. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/utils.py +1 -1
  24. {dotctl-1.0.8 → dotctl-1.1.0/src/dotctl.egg-info}/PKG-INFO +114 -19
  25. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl.egg-info/SOURCES.txt +5 -0
  26. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl.egg-info/requires.txt +1 -0
  27. dotctl-1.0.8/src/dotctl/actions/importer.py +0 -133
  28. dotctl-1.0.8/src/dotctl/actions/saver.py +0 -100
  29. dotctl-1.0.8/src/dotctl/handlers/data_handler.py +0 -142
  30. {dotctl-1.0.8 → dotctl-1.1.0}/LICENSE +0 -0
  31. {dotctl-1.0.8 → dotctl-1.1.0}/setup.cfg +0 -0
  32. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/__init__.py +0 -0
  33. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/initializer.py +0 -0
  34. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/lister.py +0 -0
  35. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/puller.py +0 -0
  36. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/switcher.py +0 -0
  37. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/actions/wiper.py +0 -0
  38. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/handlers/__init__.py +0 -0
  39. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/handlers/hooks_handler.py +0 -0
  40. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/hooks/post_apply.sh +0 -0
  41. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/hooks/pre_apply.sh +0 -0
  42. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/paths.py +0 -0
  43. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/templates/__init__.py +0 -0
  44. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/templates/dev.yaml +0 -0
  45. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/templates/other.yaml +0 -0
  46. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl/validators.py +0 -0
  47. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl.egg-info/dependency_links.txt +0 -0
  48. {dotctl-1.0.8 → dotctl-1.1.0}/src/dotctl.egg-info/entry_points.txt +0 -0
  49. {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.8
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.yml` 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.
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
- │ dotctl.yml │
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 | Description |
314
- | -------- | ---------- | ----------------------------------------------------------------- |
315
- | `save` | `location` | Base path of the tracked files (can use key like `$CONFIG_DIR`) |
316
- | | `entries` | List of files/folders to track under that location |
317
- | `export` | `location` | Base path of export files (e.g., large assets not suited for Git) |
318
- | | `entries` | List of assets or binaries to package in `.dtsv` |
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` | Pulls files defined in `save` and stores in repo |
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 the active profile.
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 my_web_server -p mYsecretp@ssw0rd
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 new profile from current active profile.
491
+ # Create a fresh profile using the detected environment or default config.
458
492
  dotctl create myserver
459
493
 
460
- # Create a empty new profile from a specific environment.
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 empty new profile from a custom config.
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.yml` 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.
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
- │ dotctl.yml │
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 | Description |
288
- | -------- | ---------- | ----------------------------------------------------------------- |
289
- | `save` | `location` | Base path of the tracked files (can use key like `$CONFIG_DIR`) |
290
- | | `entries` | List of files/folders to track under that location |
291
- | `export` | `location` | Base path of export files (e.g., large assets not suited for Git) |
292
- | | `entries` | List of assets or binaries to package in `.dtsv` |
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` | Pulls files defined in `save` and stores in repo |
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 the active profile.
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 my_web_server -p mYsecretp@ssw0rd
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 new profile from current active profile.
463
+ # Create a fresh profile using the detected environment or default config.
432
464
  dotctl create myserver
433
465
 
434
- # Create a empty new profile from a specific environment.
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 empty new profile from a custom config.
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.8"
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"
@@ -10,4 +10,4 @@ __BASE_DIR__ = os.path.dirname(os.path.abspath(__file__))
10
10
  __DEFAULT_PROFILE__ = "default"
11
11
  __EXPORT_EXTENSION__ = ".dtsv"
12
12
  __EXPORT_DATA_DIR__ = "._export_"
13
- __COMMANDS_REQ__ = ["sshpass", "rsync", "git"]
13
+ __COMMANDS_REQ__ = ["git"]
@@ -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, dest, skip_sudo=props.skip_sudo, sudo_pass=props.password
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
- if props.env or props.config:
59
- if props.config is not None and isinstance(props.config, str):
60
- props.config = Path(props.config)
61
- create_empty_branch(repo, props.profile)
62
- conf_initializer(
63
- env=props.env,
64
- custom_config=props.config,
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
- is_remote, _ = is_remote_repo(repo=repo)
77
- _, remote_profiles, active_profile, all_profiles = get_repo_branches(repo)
78
- if is_remote:
79
- if props.profile not in remote_profiles:
80
- git_fetch(repo=repo)
81
- _, remote_profiles, active_profile, all_profiles = get_repo_branches(
82
- repo
83
- )
84
- if not props.profile in remote_profiles:
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.")