dotsman 1.0.0__tar.gz

dotsman-1.0.0/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    groups:
+      github-actions:
+        patterns:
+          - "*"

dotsman-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  workflow_call:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Quality Checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57  # v8.0.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - run: uv sync --frozen
+      - run: uv run ruff format --check dots/ tests/
+      - run: uv run ruff check dots/ tests/
+      - run: uv run pyright
+
+  test:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57  # v8.0.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - run: uv sync --frozen
+      - run: uv run pytest

dotsman-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,67 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    name: CI
+    uses: ./.github/workflows/ci.yml
+
+  check-version:
+    name: Version Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - name: Verify tag matches package version
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          TAG_VERSION="${TAG#v}"
+          PKG_VERSION=$(python3 -c "
+          import re
+          with open('pyproject.toml') as f:
+              for line in f:
+                  m = re.match(r'^version\s*=\s*\"(.+)\"', line)
+                  if m:
+                      print(m.group(1))
+                      break
+          ")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag version ($TAG_VERSION) does not match package version ($PKG_VERSION)"
+            exit 1
+          fi
+          echo "Version check passed: $TAG_VERSION"
+
+  publish:
+    name: Publish
+    runs-on: ubuntu-latest
+    needs:
+      - ci
+      - check-version
+    permissions:
+      id-token: write
+      contents: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dotsman
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57  # v8.0.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - name: Build package
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: gh release create "$TAG" dist/* --generate-notes

dotsman-1.0.0/.gitignore

@@ -0,0 +1,152 @@
+# Created by .ignore support plugin (hsz.mobi)
+### JetBrains template
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and Webstorm
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff:
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/dictionaries
+.idea/shelf
+
+# Sensitive or high-churn files:
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.xml
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+
+# Gradle:
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# CMake
+cmake-build-debug/
+
+# Mongo Explorer plugin:
+.idea/**/mongoSettings.xml
+
+## File-based project format:
+*.iws
+
+## Plugin-specific files:
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/

dotsman-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format --check
+        language: system
+        types:
+          - python
+
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check
+        language: system
+        types:
+          - python
+
+      - id: pyright
+        name: pyright
+        entry: uv run pyright
+        language: system
+        types:
+          - python
+        pass_filenames: false

dotsman-1.0.0/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2017 Mathieu Deous
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+* Neither the name of Mathieu Deous nor the names of the project contributors
+  may be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL MATHIEU DEOUS BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

dotsman-1.0.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: dotsman
+Version: 1.0.0
+Summary: Configuration files management tool
+Project-URL: Repository, https://github.com/mdeous/dots
+Author-email: Mathieu Deous <mat.deous@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: gitpython>=3.1.46
+Requires-Dist: pyrage>=1.3.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.24.1
+Description-Content-Type: text/markdown
+
+# dots
+
+![Python](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fmdeous%2Fdots%2Fmaster%2Fpyproject.toml)
+![License](https://img.shields.io/github/license/mdeous/dots)
+[![CI](https://github.com/mdeous/dots/actions/workflows/ci.yml/badge.svg)](https://github.com/mdeous/dots/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/mdeous/dots/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/mdeous/dots/actions/workflows/github-code-scanning/codeql)
+
+Yet another dotfiles management tool.
+
+## :sparkles: Features
+
+- :link: Dotfiles stored in a central folder and symlinked to their real location
+- :repeat: Automatic git versioning on every change
+- :computer: Per-machine configuration via hostname-based config sections
+- :warning: Conflict detection and resolution during sync
+- :lock: Encryption for sensitive files
+
+## :clipboard: Requirements
+
+- Python 3.12+
+- git
+
+## :package: Installation
+
+Clone the repository and install with [uv](https://docs.astral.sh/uv/):
+
+```bash
+git clone https://github.com/mdeous/dots.git
+cd dots
+uv sync
+```
+
+Or with pip:
+
+```bash
+git clone https://github.com/mdeous/dots.git
+cd dots
+pip install .
+```
+
+## :gear: Configuration
+
+The configuration file should be located at `~/.dots.conf`.
+
+Settings are organized in sections named after the machine's hostname. The `[DEFAULT]` section provides fallback values used when no hostname-specific section exists.
+
+### Available settings
+
+| Key             | Description                                                               | Default  |
+| --------------- | ------------------------------------------------------------------------- | -------- |
+| `repo_dir`      | Path to the dotfiles repository                                           | `~/dots` |
+| `age_identity`  | Path to an [age](https://age-encryption.org) identity file for encryption | _none_   |
+| `ignored_files` | Comma-separated list of glob patterns to skip during sync                 | _none_   |
+
+### Example
+
+```ini
+[DEFAULT]
+repo_dir = ~/dots
+
+[work-laptop]
+repo_dir = ~/dotfiles
+ignored_files = .bashrc, .config/personal/*
+
+[home-desktop]
+age_identity = ~/.age/dots.key
+```
+
+## :rocket: Usage
+
+### Global options
+
+```text
+dots [--config PATH] [--verbose] [--version] COMMAND
+```
+
+| Option      | Short | Description                                   |
+| ----------- | ----- | --------------------------------------------- |
+| `--config`  | `-c`  | Path to config file (default: `~/.dots.conf`) |
+| `--verbose` | `-v`  | Display debug information                     |
+| `--version` | `-V`  | Display version and exit                      |
+
+### `dots add <file>`
+
+Add a file to the repository. The file is copied into the repo and replaced with a symlink.
+
+```bash
+dots add ~/.bashrc
+dots add ~/.config/git/config
+```
+
+| Option      | Short | Description                                      |
+| ----------- | ----- | ------------------------------------------------ |
+| `--encrypt` | `-e`  | Encrypt the file with age before storing in repo |
+
+When `--encrypt` is used, the file is stored as a `.age` file in the repo (encrypted at rest), with a decrypted working copy in a gitignored `.decrypted/` directory. The symlink points to the decrypted copy so the file remains usable. Requires `age_identity` to be set in the config.
+
+### `dots remove <file>`
+
+Remove a file from the repository. The symlink is replaced with the original file.
+
+```bash
+dots remove ~/.bashrc
+```
+
+### `dots list`
+
+List all files in the repository and their sync status.
+
+```bash
+dots list
+```
+
+### `dots sync`
+
+Synchronize the repository with the filesystem. Creates missing symlinks and detects conflicts.
+
+```bash
+dots sync
+```
+
+| Option           | Short | Description                                    |
+| ---------------- | ----- | ---------------------------------------------- |
+| `--force-relink` | `-r`  | Overwrite links that point to the wrong target |
+| `--force-add`    | `-a`  | Overwrite the repo version with the local file |
+| `--force-link`   | `-l`  | Overwrite the local file with the repo version |
+
+`--force-add` and `--force-link` are mutually exclusive. Without force flags, `dots` prompts interactively when conflicts are found.
+
+## :lock: Encryption
+
+Sensitive dotfiles can be encrypted at rest using [age](https://age-encryption.org). Encrypted files are safe to push to public repositories.
+
+### Setup
+
+1. Generate an age identity:
+
+   ```bash
+   age-keygen -o ~/.age/dots.key
+   ```
+
+2. Add the identity path to your config (`~/.dots.conf`):
+
+   ```ini
+   [DEFAULT]
+   age_identity = ~/.age/dots.key
+   ```
+
+3. Add files with encryption:
+
+   ```bash
+   dots add --encrypt ~/.config/secrets.env
+   ```
+
+### How it works
+
+- Encrypted files are stored in the repo with a `.age` extension (e.g., `secrets.env.age`)
+- Decrypted working copies live in a gitignored `.decrypted/` directory inside the repo
+- Symlinks point to the decrypted copies, so files are usable as normal
+- `dots sync` detects changes to decrypted files and re-encrypts them automatically
+- On a new machine, `dots sync` decrypts all `.age` files and creates symlinks
+- If the age identity is not configured, encrypted files are skipped with a warning during sync
+
+## :scroll: License
+
+BSD 3-Clause. See [LICENSE](LICENSE) for details.

dotsman-1.0.0/README.md

@@ -0,0 +1,166 @@
+# dots
+
+![Python](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fmdeous%2Fdots%2Fmaster%2Fpyproject.toml)
+![License](https://img.shields.io/github/license/mdeous/dots)
+[![CI](https://github.com/mdeous/dots/actions/workflows/ci.yml/badge.svg)](https://github.com/mdeous/dots/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/mdeous/dots/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/mdeous/dots/actions/workflows/github-code-scanning/codeql)
+
+Yet another dotfiles management tool.
+
+## :sparkles: Features
+
+- :link: Dotfiles stored in a central folder and symlinked to their real location
+- :repeat: Automatic git versioning on every change
+- :computer: Per-machine configuration via hostname-based config sections
+- :warning: Conflict detection and resolution during sync
+- :lock: Encryption for sensitive files
+
+## :clipboard: Requirements
+
+- Python 3.12+
+- git
+
+## :package: Installation
+
+Clone the repository and install with [uv](https://docs.astral.sh/uv/):
+
+```bash
+git clone https://github.com/mdeous/dots.git
+cd dots
+uv sync
+```
+
+Or with pip:
+
+```bash
+git clone https://github.com/mdeous/dots.git
+cd dots
+pip install .
+```
+
+## :gear: Configuration
+
+The configuration file should be located at `~/.dots.conf`.
+
+Settings are organized in sections named after the machine's hostname. The `[DEFAULT]` section provides fallback values used when no hostname-specific section exists.
+
+### Available settings
+
+| Key             | Description                                                               | Default  |
+| --------------- | ------------------------------------------------------------------------- | -------- |
+| `repo_dir`      | Path to the dotfiles repository                                           | `~/dots` |
+| `age_identity`  | Path to an [age](https://age-encryption.org) identity file for encryption | _none_   |
+| `ignored_files` | Comma-separated list of glob patterns to skip during sync                 | _none_   |
+
+### Example
+
+```ini
+[DEFAULT]
+repo_dir = ~/dots
+
+[work-laptop]
+repo_dir = ~/dotfiles
+ignored_files = .bashrc, .config/personal/*
+
+[home-desktop]
+age_identity = ~/.age/dots.key
+```
+
+## :rocket: Usage
+
+### Global options
+
+```text
+dots [--config PATH] [--verbose] [--version] COMMAND
+```
+
+| Option      | Short | Description                                   |
+| ----------- | ----- | --------------------------------------------- |
+| `--config`  | `-c`  | Path to config file (default: `~/.dots.conf`) |
+| `--verbose` | `-v`  | Display debug information                     |
+| `--version` | `-V`  | Display version and exit                      |
+
+### `dots add <file>`
+
+Add a file to the repository. The file is copied into the repo and replaced with a symlink.
+
+```bash
+dots add ~/.bashrc
+dots add ~/.config/git/config
+```
+
+| Option      | Short | Description                                      |
+| ----------- | ----- | ------------------------------------------------ |
+| `--encrypt` | `-e`  | Encrypt the file with age before storing in repo |
+
+When `--encrypt` is used, the file is stored as a `.age` file in the repo (encrypted at rest), with a decrypted working copy in a gitignored `.decrypted/` directory. The symlink points to the decrypted copy so the file remains usable. Requires `age_identity` to be set in the config.
+
+### `dots remove <file>`
+
+Remove a file from the repository. The symlink is replaced with the original file.
+
+```bash
+dots remove ~/.bashrc
+```
+
+### `dots list`
+
+List all files in the repository and their sync status.
+
+```bash
+dots list
+```
+
+### `dots sync`
+
+Synchronize the repository with the filesystem. Creates missing symlinks and detects conflicts.
+
+```bash
+dots sync
+```
+
+| Option           | Short | Description                                    |
+| ---------------- | ----- | ---------------------------------------------- |
+| `--force-relink` | `-r`  | Overwrite links that point to the wrong target |
+| `--force-add`    | `-a`  | Overwrite the repo version with the local file |
+| `--force-link`   | `-l`  | Overwrite the local file with the repo version |
+
+`--force-add` and `--force-link` are mutually exclusive. Without force flags, `dots` prompts interactively when conflicts are found.
+
+## :lock: Encryption
+
+Sensitive dotfiles can be encrypted at rest using [age](https://age-encryption.org). Encrypted files are safe to push to public repositories.
+
+### Setup
+
+1. Generate an age identity:
+
+   ```bash
+   age-keygen -o ~/.age/dots.key
+   ```
+
+2. Add the identity path to your config (`~/.dots.conf`):
+
+   ```ini
+   [DEFAULT]
+   age_identity = ~/.age/dots.key
+   ```
+
+3. Add files with encryption:
+
+   ```bash
+   dots add --encrypt ~/.config/secrets.env
+   ```
+
+### How it works
+
+- Encrypted files are stored in the repo with a `.age` extension (e.g., `secrets.env.age`)
+- Decrypted working copies live in a gitignored `.decrypted/` directory inside the repo
+- Symlinks point to the decrypted copies, so files are usable as normal
+- `dots sync` detects changes to decrypted files and re-encrypts them automatically
+- On a new machine, `dots sync` decrypts all `.age` files and creates symlinks
+- If the age identity is not configured, encrypted files are skipped with a warning during sync
+
+## :scroll: License
+
+BSD 3-Clause. See [LICENSE](LICENSE) for details.

dotsman-1.0.0/dots/__init__.py

@@ -0,0 +1 @@
+VERSION = "1.0.0"