dotctl 1.1.0__tar.gz → 1.1.2__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 (46) hide show
  1. {dotctl-1.1.0/src/dotctl.egg-info → dotctl-1.1.2}/PKG-INFO +28 -14
  2. {dotctl-1.1.0 → dotctl-1.1.2}/README.md +25 -10
  3. {dotctl-1.1.0 → dotctl-1.1.2}/pyproject.toml +2 -2
  4. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/actions/activator.py +4 -0
  5. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/actions/differ.py +24 -4
  6. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/actions/exporter.py +4 -0
  7. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/actions/importer.py +4 -0
  8. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/actions/saver.py +10 -1
  9. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/actions/status.py +11 -13
  10. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/arg_manager.py +5 -0
  11. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/handlers/config_handler.py +48 -2
  12. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/handlers/data_handler.py +5 -1
  13. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/handlers/diff_handler.py +90 -11
  14. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/handlers/status_handler.py +37 -4
  15. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/main.py +2 -1
  16. {dotctl-1.1.0 → dotctl-1.1.2/src/dotctl.egg-info}/PKG-INFO +28 -14
  17. {dotctl-1.1.0 → dotctl-1.1.2}/LICENSE +0 -0
  18. {dotctl-1.1.0 → dotctl-1.1.2}/setup.cfg +0 -0
  19. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/__init__.py +0 -0
  20. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/actions/__init__.py +0 -0
  21. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/actions/creator.py +0 -0
  22. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/actions/initializer.py +0 -0
  23. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/actions/lister.py +0 -0
  24. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/actions/puller.py +0 -0
  25. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/actions/remover.py +0 -0
  26. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/actions/switcher.py +0 -0
  27. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/actions/wiper.py +0 -0
  28. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/exception.py +0 -0
  29. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/handlers/__init__.py +0 -0
  30. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/handlers/git_handler.py +0 -0
  31. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/handlers/hooks_handler.py +0 -0
  32. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/handlers/sudo_handler.py +0 -0
  33. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/hooks/post_apply.sh +0 -0
  34. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/hooks/pre_apply.sh +0 -0
  35. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/paths.py +0 -0
  36. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/templates/__init__.py +0 -0
  37. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/templates/dev.yaml +0 -0
  38. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/templates/kde.yaml +0 -0
  39. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/templates/other.yaml +0 -0
  40. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/utils.py +0 -0
  41. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl/validators.py +0 -0
  42. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl.egg-info/SOURCES.txt +0 -0
  43. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl.egg-info/dependency_links.txt +0 -0
  44. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl.egg-info/entry_points.txt +0 -0
  45. {dotctl-1.1.0 → dotctl-1.1.2}/src/dotctl.egg-info/requires.txt +0 -0
  46. {dotctl-1.1.0 → dotctl-1.1.2}/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.1.0
3
+ Version: 1.1.2
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
@@ -8,11 +8,10 @@ Project-URL: Homepage, https://github.com/pankajackson/dotctl
8
8
  Project-URL: Bug Tracker, https://github.com/pankajackson/dotctl/issues
9
9
  Project-URL: Source, https://github.com/pankajackson/dotctl
10
10
  Keywords: dotfiles,config,settings,backup,dotfile-manager
11
- Classifier: Programming Language :: Python :: 3.10
12
- Classifier: Programming Language :: Python :: 3.11
13
11
  Classifier: Programming Language :: Python :: 3.12
14
12
  Classifier: Programming Language :: Python :: 3.13
15
- Classifier: Development Status :: 4 - Beta
13
+ Classifier: Programming Language :: Python :: 3.14
14
+ Classifier: Development Status :: 5 - Production/Stable
16
15
  Classifier: Intended Audience :: End Users/Desktop
17
16
  Classifier: Operating System :: MacOS
18
17
  Classifier: Operating System :: POSIX :: Linux
@@ -127,6 +126,10 @@ Each `save` or `export` section may set `required_sudo: true` when its configure
127
126
  location should be accessed through sudo. If `sudo` is omitted or `false`,
128
127
  dotctl first uses normal access and asks for sudo only if the path is restricted.
129
128
  At the prompt, you can provide a password or skip the current path/all paths.
129
+ Sections may also set `ignore_patterns` to exclude matching paths from save,
130
+ apply, export, import, status, and diff operations. Patterns use Python's
131
+ `fnmatch` syntax and are matched against paths relative to the section's
132
+ `location`; matching directories exclude their contents too.
130
133
 
131
134
  ---
132
135
 
@@ -138,6 +141,10 @@ save:
138
141
  location: $HOME
139
142
  entries:
140
143
  - test.txt
144
+ ignore_patterns:
145
+ - "*.pdf"
146
+ - "somedir/*.jpg"
147
+ - "logs/apache_web_*.log"
141
148
 
142
149
  export:
143
150
  share_folder:
@@ -323,14 +330,16 @@ This diagram shows the typical lifecycle of using a `dotctl` profile, from savin
323
330
 
324
331
  ## 📊 Profile Block Table
325
332
 
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 |
333
+ | Section | Field | Description |
334
+ | -------- | ----------------- | ----------------------------------------------------------------- |
335
+ | `save` | `location` | Base path of tracked files (can use a key like `$CONFIG_DIR`) |
336
+ | | `entries` | Files/folders to track under that location |
337
+ | | `required_sudo` | Whether restricted paths in this section require sudo |
338
+ | | `ignore_patterns` | fnmatch patterns excluded from every operation on the section |
339
+ | `export` | `location` | Base path of export files (e.g., large assets not suited for Git) |
340
+ | | `entries` | Assets or binaries to package in `.dtsv` |
341
+ | | `required_sudo` | Whether restricted paths in this section require sudo |
342
+ | | `ignore_patterns` | fnmatch patterns excluded from every operation on the section |
334
343
 
335
344
  ---
336
345
 
@@ -338,7 +347,7 @@ This diagram shows the typical lifecycle of using a `dotctl` profile, from savin
338
347
 
339
348
  | Action | Command | Description |
340
349
  | --------------- | ---------------------- | ----------------------------------------------------------- |
341
- | Save configs | `dotctl save` | Saves configured files to the active profile and syncs Git |
350
+ | Save configs | `dotctl save` | Saves configured files to the active profile and syncs Git |
342
351
  | Export assets | `dotctl export` | Package large, non-Git assets into `.dtsv` file |
343
352
  | Transfer assets | `scp profile.dtsv ...` | Manually copy to another machine |
344
353
  | Import assets | `dotctl import` | Unpack `.dtsv` on another system |
@@ -579,7 +588,7 @@ dotctl pull
579
588
  Inspect the current profile health and detect configuration drift between the repository and local system.
580
589
 
581
590
  ```sh
582
- dotctl status [--json] [--short]
591
+ dotctl status [--json] [--short] [--long]
583
592
  ```
584
593
 
585
594
  **Examples:**
@@ -588,8 +597,13 @@ dotctl status [--json] [--short]
588
597
  dotctl status
589
598
  dotctl status --short
590
599
  dotctl status --json
600
+ dotctl status --long
591
601
  ```
592
602
 
603
+ `--long` lists the affected files beneath each changed entry. JSON status
604
+ includes a `files` array on each entry; for directory entries its paths are
605
+ relative to that configured entry.
606
+
593
607
  ---
594
608
 
595
609
  ### 🔎 `diff`
@@ -99,6 +99,10 @@ Each `save` or `export` section may set `required_sudo: true` when its configure
99
99
  location should be accessed through sudo. If `sudo` is omitted or `false`,
100
100
  dotctl first uses normal access and asks for sudo only if the path is restricted.
101
101
  At the prompt, you can provide a password or skip the current path/all paths.
102
+ Sections may also set `ignore_patterns` to exclude matching paths from save,
103
+ apply, export, import, status, and diff operations. Patterns use Python's
104
+ `fnmatch` syntax and are matched against paths relative to the section's
105
+ `location`; matching directories exclude their contents too.
102
106
 
103
107
  ---
104
108
 
@@ -110,6 +114,10 @@ save:
110
114
  location: $HOME
111
115
  entries:
112
116
  - test.txt
117
+ ignore_patterns:
118
+ - "*.pdf"
119
+ - "somedir/*.jpg"
120
+ - "logs/apache_web_*.log"
113
121
 
114
122
  export:
115
123
  share_folder:
@@ -295,14 +303,16 @@ This diagram shows the typical lifecycle of using a `dotctl` profile, from savin
295
303
 
296
304
  ## 📊 Profile Block Table
297
305
 
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 |
306
+ | Section | Field | Description |
307
+ | -------- | ----------------- | ----------------------------------------------------------------- |
308
+ | `save` | `location` | Base path of tracked files (can use a key like `$CONFIG_DIR`) |
309
+ | | `entries` | Files/folders to track under that location |
310
+ | | `required_sudo` | Whether restricted paths in this section require sudo |
311
+ | | `ignore_patterns` | fnmatch patterns excluded from every operation on the section |
312
+ | `export` | `location` | Base path of export files (e.g., large assets not suited for Git) |
313
+ | | `entries` | Assets or binaries to package in `.dtsv` |
314
+ | | `required_sudo` | Whether restricted paths in this section require sudo |
315
+ | | `ignore_patterns` | fnmatch patterns excluded from every operation on the section |
306
316
 
307
317
  ---
308
318
 
@@ -310,7 +320,7 @@ This diagram shows the typical lifecycle of using a `dotctl` profile, from savin
310
320
 
311
321
  | Action | Command | Description |
312
322
  | --------------- | ---------------------- | ----------------------------------------------------------- |
313
- | Save configs | `dotctl save` | Saves configured files to the active profile and syncs Git |
323
+ | Save configs | `dotctl save` | Saves configured files to the active profile and syncs Git |
314
324
  | Export assets | `dotctl export` | Package large, non-Git assets into `.dtsv` file |
315
325
  | Transfer assets | `scp profile.dtsv ...` | Manually copy to another machine |
316
326
  | Import assets | `dotctl import` | Unpack `.dtsv` on another system |
@@ -551,7 +561,7 @@ dotctl pull
551
561
  Inspect the current profile health and detect configuration drift between the repository and local system.
552
562
 
553
563
  ```sh
554
- dotctl status [--json] [--short]
564
+ dotctl status [--json] [--short] [--long]
555
565
  ```
556
566
 
557
567
  **Examples:**
@@ -560,8 +570,13 @@ dotctl status [--json] [--short]
560
570
  dotctl status
561
571
  dotctl status --short
562
572
  dotctl status --json
573
+ dotctl status --long
563
574
  ```
564
575
 
576
+ `--long` lists the affected files beneath each changed entry. JSON status
577
+ includes a `files` array on each entry; for directory entries its paths are
578
+ relative to that configured entry.
579
+
565
580
  ---
566
581
 
567
582
  ### 🔎 `diff`
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "dotctl"
7
- version = "v1.1.0"
7
+ version = "v1.1.2"
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"
@@ -12,7 +12,7 @@ license-files = [ "LICENSE",]
12
12
  requires-python = ">=3.10"
13
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 :: MacOS", "Operating System :: POSIX :: Linux", "Topic :: System :: Archiving :: Backup", "Topic :: Utilities",]
15
+ classifiers = [ "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Programming Language :: Python :: 3.14", "Development Status :: 5 - Production/Stable", "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"
@@ -4,6 +4,7 @@ from dotctl.utils import log
4
4
  from dotctl.handlers.data_handler import copy
5
5
  from dotctl.paths import app_profile_directory, app_config_file
6
6
  from dotctl.handlers.config_handler import conf_reader
7
+ from dotctl.handlers.config_handler import is_ignored, patterns_for_entry
7
8
  from dotctl.handlers.hooks_handler import run_hooks
8
9
  from dotctl.handlers.git_handler import (
9
10
  get_repo,
@@ -74,6 +75,8 @@ def apply(props: ActivatorProps) -> None:
74
75
  dest_base_dir = Path(section.location)
75
76
  log(f'Applying "{name}"...')
76
77
  for entry in section.entries:
78
+ if is_ignored(entry, section.ignore_patterns):
79
+ continue
77
80
  source = source_base_dir / entry
78
81
  dest = dest_base_dir / entry
79
82
  result = copy(
@@ -82,6 +85,7 @@ def apply(props: ActivatorProps) -> None:
82
85
  skip_sudo=props.skip_sudo,
83
86
  sudo_pass=props.password,
84
87
  required_sudo=section.required_sudo,
88
+ ignore_patterns=patterns_for_entry(entry, section.ignore_patterns),
85
89
  )
86
90
 
87
91
  # Updated props
@@ -4,7 +4,7 @@ import subprocess
4
4
  import sys
5
5
 
6
6
  from dotctl.paths import app_profile_directory, app_config_file
7
- from dotctl.handlers.config_handler import conf_reader
7
+ from dotctl.handlers.config_handler import conf_reader, is_ignored
8
8
  from dotctl.handlers.diff_handler import (
9
9
  get_file_diff,
10
10
  render_side_by_side,
@@ -52,6 +52,8 @@ def diff(props: DiffProps) -> None:
52
52
  repo_base_dir = props.profile_dir / name
53
53
 
54
54
  for entry in section.entries:
55
+ if is_ignored(entry, section.ignore_patterns):
56
+ continue
55
57
 
56
58
  source_root = source_base_dir / entry
57
59
  repo_root = repo_base_dir / entry
@@ -66,17 +68,33 @@ def diff(props: DiffProps) -> None:
66
68
  continue
67
69
  resolved_source = source_root.resolve()
68
70
  resolved_repo = repo_root.resolve()
69
- if target_path != resolved_source and resolved_source in target_path.parents:
71
+ if (
72
+ target_path != resolved_source
73
+ and resolved_source in target_path.parents
74
+ ):
70
75
  relative_target = target_path.relative_to(resolved_source)
71
76
  source = source_root / relative_target
72
77
  repo_file = repo_root / relative_target
73
- elif target_path != resolved_repo and resolved_repo in target_path.parents:
78
+ elif (
79
+ target_path != resolved_repo
80
+ and resolved_repo in target_path.parents
81
+ ):
74
82
  relative_target = target_path.relative_to(resolved_repo)
75
83
  source = source_root / relative_target
76
84
  repo_file = repo_root / relative_target
85
+ if source != source_root and is_ignored(
86
+ source.relative_to(source_root),
87
+ section.ignore_patterns,
88
+ base_path=Path(entry),
89
+ ):
90
+ continue
77
91
  try:
78
92
  diff_lines = get_file_diff(
79
- source, repo_file, required_sudo=section.required_sudo
93
+ source,
94
+ repo_file,
95
+ required_sudo=section.required_sudo,
96
+ ignore_patterns=section.ignore_patterns,
97
+ ignore_base=Path(entry),
80
98
  )
81
99
  except (PermissionError, subprocess.CalledProcessError):
82
100
  inaccessible_paths.append(source)
@@ -93,6 +111,8 @@ def diff(props: DiffProps) -> None:
93
111
  source,
94
112
  repo_file,
95
113
  required_sudo=section.required_sudo,
114
+ ignore_patterns=section.ignore_patterns,
115
+ ignore_base=Path(entry),
96
116
  )
97
117
  except (PermissionError, subprocess.CalledProcessError):
98
118
  inaccessible_paths.append(source)
@@ -6,6 +6,7 @@ from dotctl.utils import log
6
6
  from dotctl.handlers.data_handler import copy
7
7
  from dotctl.paths import app_profile_directory, app_config_file, home_path
8
8
  from dotctl.handlers.config_handler import conf_reader
9
+ from dotctl.handlers.config_handler import is_ignored, patterns_for_entry
9
10
  from dotctl.handlers.git_handler import (
10
11
  get_repo,
11
12
  get_repo_branches,
@@ -89,6 +90,8 @@ def exporter(props: ExporterProps) -> None:
89
90
 
90
91
  log(f'Exporting "{name}"...')
91
92
  for entry in section.entries:
93
+ if is_ignored(entry, section.ignore_patterns):
94
+ continue
92
95
  source = source_base_dir / entry
93
96
  dest = dest_base_dir / entry
94
97
  result = copy(
@@ -98,6 +101,7 @@ def exporter(props: ExporterProps) -> None:
98
101
  sudo_pass=props.password,
99
102
  required_sudo=section.required_sudo,
100
103
  user_owned_destination=True,
104
+ ignore_patterns=patterns_for_entry(entry, section.ignore_patterns),
101
105
  )
102
106
 
103
107
  # Update props based on the result
@@ -11,6 +11,7 @@ from dotctl.utils import log
11
11
  from dotctl.handlers.data_handler import copy
12
12
  from dotctl.paths import app_profile_directory, app_home_directory, app_config_file
13
13
  from dotctl.handlers.config_handler import conf_reader
14
+ from dotctl.handlers.config_handler import is_ignored, patterns_for_entry
14
15
  from dotctl.handlers.git_handler import (
15
16
  commit_changes,
16
17
  get_repo,
@@ -133,6 +134,8 @@ def importer(props: ImporterProps) -> None:
133
134
 
134
135
  log(f'Importing "{name}"...')
135
136
  for entry in section.entries:
137
+ if is_ignored(entry, section.ignore_patterns):
138
+ continue
136
139
  source = source_base_dir / entry
137
140
  dest = dest_base_dir / entry
138
141
  result = copy(
@@ -141,6 +144,7 @@ def importer(props: ImporterProps) -> None:
141
144
  skip_sudo=props.skip_sudo,
142
145
  sudo_pass=props.password,
143
146
  required_sudo=section.required_sudo,
147
+ ignore_patterns=patterns_for_entry(entry, section.ignore_patterns),
144
148
  )
145
149
 
146
150
  # Updated props
@@ -5,7 +5,11 @@ from pathlib import Path
5
5
  from dotctl.utils import log
6
6
  from dotctl.handlers.data_handler import copy, delete
7
7
  from dotctl.paths import app_profile_directory, app_config_file
8
- from dotctl.handlers.config_handler import conf_reader
8
+ from dotctl.handlers.config_handler import (
9
+ conf_reader,
10
+ is_ignored,
11
+ patterns_for_entry,
12
+ )
9
13
  from dotctl.handlers.git_handler import (
10
14
  get_repo,
11
15
  get_repo_branches,
@@ -85,6 +89,8 @@ def _save_current_profile(
85
89
  dest_base_dir.mkdir(exist_ok=True)
86
90
  log(f'Saving "{name}"...')
87
91
  for entry in section.entries:
92
+ if is_ignored(entry, section.ignore_patterns):
93
+ continue
88
94
  source = source_base_dir / entry
89
95
  dest = dest_base_dir / entry
90
96
  result = copy(
@@ -96,6 +102,7 @@ def _save_current_profile(
96
102
  required_sudo=section.required_sudo,
97
103
  user_owned_destination=True,
98
104
  skipped_paths=skipped_paths,
105
+ ignore_patterns=patterns_for_entry(entry, section.ignore_patterns),
99
106
  )
100
107
 
101
108
  # Updated props
@@ -139,6 +146,8 @@ def _save_current_profile(
139
146
  )
140
147
  for candidate in candidates:
141
148
  relative_path = candidate.relative_to(dot)
149
+ if is_ignored(relative_path, section.ignore_patterns):
150
+ continue
142
151
  keep = any(
143
152
  relative_path == configured
144
153
  or relative_path in configured.parents
@@ -69,16 +69,18 @@ class StatusProps:
69
69
  profile_dir: Path
70
70
  json: bool
71
71
  short: bool
72
+ long: bool
72
73
 
73
74
 
74
75
  status_default_props = StatusProps(
75
76
  profile_dir=Path(app_profile_directory),
76
77
  json=False,
77
78
  short=False,
79
+ long=False,
78
80
  )
79
81
 
80
82
 
81
- def render_full(report: StatusReport):
83
+ def render_full(report: StatusReport, *, long: bool = False):
82
84
 
83
85
  profile = report.profile
84
86
  config = report.config
@@ -129,11 +131,7 @@ def render_full(report: StatusReport):
129
131
 
130
132
  print(f"ℹ not present at either location: {len(drift.not_present_files)}")
131
133
 
132
- changed = (
133
- drift.modified_files
134
- + drift.missing_files
135
- + drift.inaccessible_files
136
- )
134
+ changed = drift.modified_files + drift.missing_files + drift.inaccessible_files
137
135
 
138
136
  if changed:
139
137
 
@@ -143,6 +141,9 @@ def render_full(report: StatusReport):
143
141
 
144
142
  for f in changed:
145
143
  print(f" - {f.path}")
144
+ if long:
145
+ for path in f.files:
146
+ print(f" {path}")
146
147
 
147
148
  print()
148
149
 
@@ -208,6 +209,7 @@ def render_json(report: StatusReport):
208
209
  "entry": f.entry,
209
210
  "path": str(f.path),
210
211
  "state": f.state.value,
212
+ "files": f.files,
211
213
  }
212
214
 
213
215
  output = {
@@ -238,12 +240,8 @@ def render_json(report: StatusReport):
238
240
  "modified_files": [encode_file(f) for f in drift.modified_files],
239
241
  "missing_files": [encode_file(f) for f in drift.missing_files],
240
242
  "synced_files": [encode_file(f) for f in drift.synced_files],
241
- "not_present_files": [
242
- encode_file(f) for f in drift.not_present_files
243
- ],
244
- "inaccessible_files": [
245
- encode_file(f) for f in drift.inaccessible_files
246
- ],
243
+ "not_present_files": [encode_file(f) for f in drift.not_present_files],
244
+ "inaccessible_files": [encode_file(f) for f in drift.inaccessible_files],
247
245
  }
248
246
 
249
247
  print(json.dumps(output, indent=2))
@@ -439,4 +437,4 @@ def status(props: StatusProps) -> None:
439
437
  render_short(report)
440
438
  else:
441
439
  log("Fetching status...")
442
- render_full(report)
440
+ render_full(report, long=props.long)
@@ -320,6 +320,11 @@ def get_parser() -> argparse.ArgumentParser:
320
320
  action="store_true",
321
321
  help="Print status in short format",
322
322
  )
323
+ status_parser.add_argument(
324
+ "--long",
325
+ action="store_true",
326
+ help="List affected files for each changed entry",
327
+ )
323
328
 
324
329
  # Wipe Parser
325
330
  wipe_parser = subparsers.add_parser("wipe", help="Wipe Profiles")
@@ -2,7 +2,8 @@ import os
2
2
  import yaml
3
3
  import re
4
4
  import shutil
5
- from dataclasses import dataclass
5
+ import fnmatch
6
+ from dataclasses import dataclass, field
6
7
  from pathlib import Path
7
8
  from dotctl import __BASE_DIR__
8
9
  from dotctl.paths import (
@@ -23,6 +24,41 @@ class EntryConfig:
23
24
  entries: list[str]
24
25
  location: str
25
26
  required_sudo: bool = False
27
+ ignore_patterns: list[str] = field(default_factory=list)
28
+
29
+
30
+ def is_ignored(
31
+ path: str | Path,
32
+ patterns: list[str],
33
+ *,
34
+ base_path: str | Path = Path(),
35
+ ) -> bool:
36
+ """Match a path relative to the section location, including ignored dirs."""
37
+ if not patterns:
38
+ return False
39
+ path = Path(base_path) / path
40
+ parts = path.parts
41
+ return any(
42
+ fnmatch.fnmatch(path.as_posix(), pattern)
43
+ or any(fnmatch.fnmatch(Path(*parts[:i]).as_posix(), pattern) for i in range(1, len(parts)))
44
+ for pattern in patterns
45
+ )
46
+
47
+
48
+ def patterns_for_entry(entry: str | Path, patterns: list[str]) -> list[str]:
49
+ """Translate section-relative patterns for rsync's entry-relative paths."""
50
+ entry_parts = Path(entry).parts
51
+ relative_patterns = []
52
+ for pattern in patterns:
53
+ pattern_parts = Path(pattern).parts
54
+ if len(pattern_parts) > len(entry_parts) and all(
55
+ fnmatch.fnmatch(entry_part, pattern_part)
56
+ for entry_part, pattern_part in zip(entry_parts, pattern_parts)
57
+ ):
58
+ relative_patterns.append(Path(*pattern_parts[len(entry_parts) :]).as_posix())
59
+ else:
60
+ relative_patterns.append(pattern)
61
+ return relative_patterns
26
62
 
27
63
 
28
64
  @dataclass
@@ -96,11 +132,21 @@ def conf_reader(config_file: Path = Path(app_config_file)) -> Config:
96
132
  raise ValueError(
97
133
  f"Config section '{name}'.entries must be a list of paths."
98
134
  )
135
+ ignore_patterns = values.get("ignore_patterns", [])
136
+ if not isinstance(ignore_patterns, list) or not all(
137
+ isinstance(pattern, str) for pattern in ignore_patterns
138
+ ):
139
+ raise ValueError(
140
+ f"Config section '{name}'.ignore_patterns must be a list of patterns."
141
+ )
99
142
  location = values.get("location")
100
143
  if not isinstance(location, str):
101
144
  raise ValueError(f"Config section '{name}'.location must be a path.")
102
145
  return EntryConfig(
103
- entries=entries, location=location, required_sudo=required_sudo
146
+ entries=entries,
147
+ location=location,
148
+ required_sudo=required_sudo,
149
+ ignore_patterns=ignore_patterns,
104
150
  )
105
151
 
106
152
  return Config(
@@ -17,10 +17,11 @@ def rsync(
17
17
  sudo_pass: str | None = None,
18
18
  is_dir: bool = False,
19
19
  user_owned_destination: bool = False,
20
+ ignore_patterns: list[str] | None = None,
20
21
  ):
21
22
  """Synchronizes source to destination using rsync with optional sudo support."""
22
23
  rsync_command = "rsync"
23
- exclude_patterns = ["*.pyc", "*.pyo", ".git"]
24
+ exclude_patterns = ["*.pyc", "*.pyo", ".git", *(ignore_patterns or [])]
24
25
  exclude_options = [f"--exclude={pattern}" for pattern in exclude_patterns]
25
26
  rsync_options = ["-az", "--delete"]
26
27
 
@@ -112,6 +113,7 @@ def copy(
112
113
  required_sudo: bool = False,
113
114
  user_owned_destination: bool = False,
114
115
  skipped_paths: list[Path] | None = None,
116
+ ignore_patterns: list[str] | None = None,
115
117
  ):
116
118
  """Copies files/directories using rsync and handles sudo permission issues."""
117
119
  temp_pass = None
@@ -215,6 +217,7 @@ def copy(
215
217
  sudo_credential(temp_pass, sudo_pass),
216
218
  is_dir=is_dir,
217
219
  user_owned_destination=user_owned_destination,
220
+ ignore_patterns=ignore_patterns,
218
221
  )
219
222
  except PermissionError:
220
223
  if not skip_sudo:
@@ -227,6 +230,7 @@ def copy(
227
230
  credential,
228
231
  is_dir=is_dir,
229
232
  user_owned_destination=user_owned_destination,
233
+ ignore_patterns=ignore_patterns,
230
234
  )
231
235
  else:
232
236
  log(
@@ -9,12 +9,18 @@ from dotctl.handlers.sudo_handler import (
9
9
  path_exists,
10
10
  read_path_text,
11
11
  )
12
+ from dotctl.handlers.config_handler import is_ignored
12
13
 
13
14
  console = Console()
14
15
 
15
16
 
16
17
  def get_file_diff(
17
- source: Path, dest: Path, *, required_sudo: bool = False
18
+ source: Path,
19
+ dest: Path,
20
+ *,
21
+ required_sudo: bool = False,
22
+ ignore_patterns: list[str] | None = None,
23
+ ignore_base: Path = Path(),
18
24
  ) -> list[str] | None:
19
25
  if not _path_exists(source, required_sudo=required_sudo) and not _path_exists(dest):
20
26
  return None
@@ -25,8 +31,15 @@ def get_file_diff(
25
31
  # Configured entries may be directories. Compare their files by relative
26
32
  # path so additions and removals are reported as well as content changes.
27
33
  if is_directory(source, required_sudo=required_sudo) or is_directory(dest):
28
- source_files = _directory_files(source, required_sudo=required_sudo)
29
- dest_files = _directory_files(dest)
34
+ source_files = _directory_files(
35
+ source,
36
+ required_sudo=required_sudo,
37
+ ignore_patterns=ignore_patterns,
38
+ ignore_base=ignore_base,
39
+ )
40
+ dest_files = _directory_files(
41
+ dest, ignore_patterns=ignore_patterns, ignore_base=ignore_base
42
+ )
30
43
  diffs: list[str] = []
31
44
  for relative_path in sorted(source_files.keys() | dest_files.keys()):
32
45
  source_file = (
@@ -52,16 +65,65 @@ def get_file_diff(
52
65
 
53
66
 
54
67
  def _directory_files(
55
- directory: Path, *, required_sudo: bool = False
68
+ directory: Path,
69
+ *,
70
+ required_sudo: bool = False,
71
+ ignore_patterns: list[str] | None = None,
72
+ ignore_base: Path = Path(),
56
73
  ) -> dict[Path, Path]:
57
74
  if not is_directory(directory, required_sudo=required_sudo):
58
75
  return {}
59
76
  return {
60
77
  path.relative_to(directory): path
61
78
  for path in list_path_files(directory, required_sudo=required_sudo)
79
+ if not is_ignored(
80
+ path.relative_to(directory), ignore_patterns or [], base_path=ignore_base
81
+ )
62
82
  }
63
83
 
64
84
 
85
+ def get_changed_file_paths(
86
+ source: Path,
87
+ dest: Path,
88
+ entry: str,
89
+ *,
90
+ required_sudo: bool = False,
91
+ ignore_patterns: list[str] | None = None,
92
+ ignore_base: Path = Path(),
93
+ ) -> list[str]:
94
+ """Return changed file names relative to a configured entry."""
95
+ if is_symlink(source, required_sudo=required_sudo) or is_symlink(dest):
96
+ return [entry] if _get_single_file_diff(
97
+ source, dest, required_sudo=required_sudo
98
+ ) else []
99
+
100
+ if is_directory(source, required_sudo=required_sudo) or is_directory(dest):
101
+ source_files = _directory_files(
102
+ source,
103
+ required_sudo=required_sudo,
104
+ ignore_patterns=ignore_patterns,
105
+ ignore_base=ignore_base,
106
+ )
107
+ dest_files = _directory_files(
108
+ dest, ignore_patterns=ignore_patterns, ignore_base=ignore_base
109
+ )
110
+ changed = []
111
+ for relative_path in sorted(source_files.keys() | dest_files.keys()):
112
+ source_file = source_files.get(relative_path, source / relative_path)
113
+ dest_file = dest_files.get(relative_path, dest / relative_path)
114
+ if _get_single_file_diff(
115
+ source_file,
116
+ dest_file,
117
+ required_sudo=required_sudo and source_file in source_files.values(),
118
+ ):
119
+ changed.append(relative_path.as_posix())
120
+ return changed
121
+
122
+ return [entry] if _get_single_file_diff(
123
+ source, dest, required_sudo=required_sudo
124
+ ) else []
125
+
126
+
65
127
  def _path_exists(path: Path, *, required_sudo: bool = False) -> bool:
66
128
  try:
67
129
  path.lstat()
@@ -155,11 +217,25 @@ def render_colored_diff(lines: list[str]) -> None:
155
217
  console.print(line)
156
218
 
157
219
 
158
- def render_side_by_side(source, dest, *, required_sudo: bool = False):
220
+ def render_side_by_side(
221
+ source,
222
+ dest,
223
+ *,
224
+ required_sudo: bool = False,
225
+ ignore_patterns: list[str] | None = None,
226
+ ignore_base: Path = Path(),
227
+ ):
159
228
 
160
229
  if is_directory(source, required_sudo=required_sudo) or is_directory(dest):
161
- source_files = _directory_files(source, required_sudo=required_sudo)
162
- dest_files = _directory_files(dest)
230
+ source_files = _directory_files(
231
+ source,
232
+ required_sudo=required_sudo,
233
+ ignore_patterns=ignore_patterns,
234
+ ignore_base=ignore_base,
235
+ )
236
+ dest_files = _directory_files(
237
+ dest, ignore_patterns=ignore_patterns, ignore_base=ignore_base
238
+ )
163
239
  for relative_path in sorted(source_files.keys() | dest_files.keys()):
164
240
  source_file = (
165
241
  source_files[relative_path]
@@ -175,18 +251,21 @@ def render_side_by_side(source, dest, *, required_sudo: bool = False):
175
251
  source_file,
176
252
  dest_file,
177
253
  required_sudo=required_sudo and source_file in source_files.values(),
254
+ ignore_patterns=ignore_patterns,
255
+ ignore_base=ignore_base,
178
256
  ):
179
257
  console.print(f"\n{relative_path}", style="bold")
180
258
  render_side_by_side(
181
259
  source_file,
182
260
  dest_file,
183
- required_sudo=required_sudo and source_file in source_files.values(),
261
+ required_sudo=required_sudo
262
+ and source_file in source_files.values(),
263
+ ignore_patterns=ignore_patterns,
264
+ ignore_base=ignore_base,
184
265
  )
185
266
  return
186
267
 
187
- source_lines = _read_lines(
188
- source, keepends=False, required_sudo=required_sudo
189
- )
268
+ source_lines = _read_lines(source, keepends=False, required_sudo=required_sudo)
190
269
  dest_lines = _read_lines(dest, keepends=False)
191
270
 
192
271
  matcher = SequenceMatcher(None, dest_lines, source_lines)
@@ -4,7 +4,8 @@ from pathlib import Path
4
4
  import subprocess
5
5
 
6
6
  from dotctl.handlers.config_handler import Config
7
- from dotctl.handlers.diff_handler import get_file_diff
7
+ from dotctl.handlers.config_handler import is_ignored
8
+ from dotctl.handlers.diff_handler import get_file_diff, get_changed_file_paths
8
9
  from dotctl.handlers.sudo_handler import path_exists
9
10
 
10
11
 
@@ -77,6 +78,7 @@ class StatusEntry:
77
78
  entry: str
78
79
  state: FileState
79
80
  path: Path
81
+ files: list[str] = field(default_factory=list)
80
82
 
81
83
 
82
84
  @dataclass
@@ -108,7 +110,9 @@ class DriftReport:
108
110
 
109
111
 
110
112
  def get_file_state(
111
- source: Path, repo_file: Path, *, required_sudo: bool = False
113
+ source: Path, repo_file: Path, *, required_sudo: bool = False,
114
+ ignore_patterns: list[str] | None = None,
115
+ ignore_base: Path = Path(),
112
116
  ) -> FileState:
113
117
  source_exists = _path_presence(source, required_sudo=required_sudo)
114
118
  repo_exists = _path_presence(repo_file)
@@ -126,7 +130,13 @@ def get_file_state(
126
130
  return FileState.NOT_PRESENT
127
131
 
128
132
  try:
129
- diff = get_file_diff(source, repo_file, required_sudo=required_sudo)
133
+ diff = get_file_diff(
134
+ source,
135
+ repo_file,
136
+ required_sudo=required_sudo,
137
+ ignore_patterns=ignore_patterns,
138
+ ignore_base=ignore_base,
139
+ )
130
140
  except (PermissionError, subprocess.CalledProcessError):
131
141
  return FileState.INACCESSIBLE
132
142
 
@@ -158,12 +168,34 @@ def build_drift_report(profile_dir: Path, config: Config) -> DriftReport:
158
168
 
159
169
  for entry in section.entries:
160
170
 
171
+ if is_ignored(entry, section.ignore_patterns):
172
+ continue
173
+
161
174
  source = Path(section.location) / entry
162
175
  repo_file = profile_dir / name / entry
163
176
 
164
177
  state = get_file_state(
165
- source, repo_file, required_sudo=section.required_sudo
178
+ source, repo_file, required_sudo=section.required_sudo,
179
+ ignore_patterns=section.ignore_patterns,
180
+ ignore_base=Path(entry),
166
181
  )
182
+ changed_files = []
183
+ if state in (
184
+ FileState.MODIFIED,
185
+ FileState.MISSING_SOURCE,
186
+ FileState.MISSING_PROFILE,
187
+ ):
188
+ try:
189
+ changed_files = get_changed_file_paths(
190
+ source,
191
+ repo_file,
192
+ entry,
193
+ required_sudo=section.required_sudo,
194
+ ignore_patterns=section.ignore_patterns,
195
+ ignore_base=Path(entry),
196
+ )
197
+ except (PermissionError, subprocess.CalledProcessError):
198
+ pass
167
199
 
168
200
  results.append(
169
201
  StatusEntry(
@@ -171,6 +203,7 @@ def build_drift_report(profile_dir: Path, config: Config) -> DriftReport:
171
203
  entry=entry,
172
204
  path=source,
173
205
  state=state,
206
+ files=changed_files,
174
207
  )
175
208
  )
176
209
 
@@ -163,7 +163,7 @@ class DotCtl:
163
163
 
164
164
  def show_status(self):
165
165
  """Show status of dotfiles."""
166
- props = self._build_props(status_default_props, "json", "short")
166
+ props = self._build_props(status_default_props, "json", "short", "long")
167
167
  status(props)
168
168
 
169
169
 
@@ -221,6 +221,7 @@ def main():
221
221
  "target": getattr(args, "target", None),
222
222
  "json": getattr(args, "json", None),
223
223
  "short": getattr(args, "short", None),
224
+ "long": getattr(args, "long", None),
224
225
  }
225
226
 
226
227
  dot_ctl_obj = DotCtl(**common_args)
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dotctl
3
- Version: 1.1.0
3
+ Version: 1.1.2
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
@@ -8,11 +8,10 @@ Project-URL: Homepage, https://github.com/pankajackson/dotctl
8
8
  Project-URL: Bug Tracker, https://github.com/pankajackson/dotctl/issues
9
9
  Project-URL: Source, https://github.com/pankajackson/dotctl
10
10
  Keywords: dotfiles,config,settings,backup,dotfile-manager
11
- Classifier: Programming Language :: Python :: 3.10
12
- Classifier: Programming Language :: Python :: 3.11
13
11
  Classifier: Programming Language :: Python :: 3.12
14
12
  Classifier: Programming Language :: Python :: 3.13
15
- Classifier: Development Status :: 4 - Beta
13
+ Classifier: Programming Language :: Python :: 3.14
14
+ Classifier: Development Status :: 5 - Production/Stable
16
15
  Classifier: Intended Audience :: End Users/Desktop
17
16
  Classifier: Operating System :: MacOS
18
17
  Classifier: Operating System :: POSIX :: Linux
@@ -127,6 +126,10 @@ Each `save` or `export` section may set `required_sudo: true` when its configure
127
126
  location should be accessed through sudo. If `sudo` is omitted or `false`,
128
127
  dotctl first uses normal access and asks for sudo only if the path is restricted.
129
128
  At the prompt, you can provide a password or skip the current path/all paths.
129
+ Sections may also set `ignore_patterns` to exclude matching paths from save,
130
+ apply, export, import, status, and diff operations. Patterns use Python's
131
+ `fnmatch` syntax and are matched against paths relative to the section's
132
+ `location`; matching directories exclude their contents too.
130
133
 
131
134
  ---
132
135
 
@@ -138,6 +141,10 @@ save:
138
141
  location: $HOME
139
142
  entries:
140
143
  - test.txt
144
+ ignore_patterns:
145
+ - "*.pdf"
146
+ - "somedir/*.jpg"
147
+ - "logs/apache_web_*.log"
141
148
 
142
149
  export:
143
150
  share_folder:
@@ -323,14 +330,16 @@ This diagram shows the typical lifecycle of using a `dotctl` profile, from savin
323
330
 
324
331
  ## 📊 Profile Block Table
325
332
 
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 |
333
+ | Section | Field | Description |
334
+ | -------- | ----------------- | ----------------------------------------------------------------- |
335
+ | `save` | `location` | Base path of tracked files (can use a key like `$CONFIG_DIR`) |
336
+ | | `entries` | Files/folders to track under that location |
337
+ | | `required_sudo` | Whether restricted paths in this section require sudo |
338
+ | | `ignore_patterns` | fnmatch patterns excluded from every operation on the section |
339
+ | `export` | `location` | Base path of export files (e.g., large assets not suited for Git) |
340
+ | | `entries` | Assets or binaries to package in `.dtsv` |
341
+ | | `required_sudo` | Whether restricted paths in this section require sudo |
342
+ | | `ignore_patterns` | fnmatch patterns excluded from every operation on the section |
334
343
 
335
344
  ---
336
345
 
@@ -338,7 +347,7 @@ This diagram shows the typical lifecycle of using a `dotctl` profile, from savin
338
347
 
339
348
  | Action | Command | Description |
340
349
  | --------------- | ---------------------- | ----------------------------------------------------------- |
341
- | Save configs | `dotctl save` | Saves configured files to the active profile and syncs Git |
350
+ | Save configs | `dotctl save` | Saves configured files to the active profile and syncs Git |
342
351
  | Export assets | `dotctl export` | Package large, non-Git assets into `.dtsv` file |
343
352
  | Transfer assets | `scp profile.dtsv ...` | Manually copy to another machine |
344
353
  | Import assets | `dotctl import` | Unpack `.dtsv` on another system |
@@ -579,7 +588,7 @@ dotctl pull
579
588
  Inspect the current profile health and detect configuration drift between the repository and local system.
580
589
 
581
590
  ```sh
582
- dotctl status [--json] [--short]
591
+ dotctl status [--json] [--short] [--long]
583
592
  ```
584
593
 
585
594
  **Examples:**
@@ -588,8 +597,13 @@ dotctl status [--json] [--short]
588
597
  dotctl status
589
598
  dotctl status --short
590
599
  dotctl status --json
600
+ dotctl status --long
591
601
  ```
592
602
 
603
+ `--long` lists the affected files beneath each changed entry. JSON status
604
+ includes a `files` array on each entry; for directory entries its paths are
605
+ relative to that configured entry.
606
+
593
607
  ---
594
608
 
595
609
  ### 🔎 `diff`
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes