dotx 2.1.0__tar.gz → 2.2.1__tar.gz

{dotx-2.1.0/src/dotx.egg-info → dotx-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotx
-Version: 2.1.0
+Version: 2.2.1
 Summary: A command-line tool to install a link-farm to your dotfiles
 Author-email: Wolf <Wolf@zv.cx>
 License-Expression: MIT
@@ -28,6 +28,8 @@ Dynamic: license-file
 
 ## The Basic Idea
 
+> **Comparing dotfile managers?** See [ALTERNATIVES.md](ALTERNATIVES.md) for a detailed comparison of dotx vs GNU Stow, chezmoi, YADM, dotbot, and others.
+
 ### What `dotx` does; what it's _for_
 #### The problem
 
@@ -241,15 +243,78 @@ Installations:
 
 #### Rebuild database from filesystem
 
-If you have existing dotfile installations and an empty or missing database, use `sync` to rebuild it:
+If you have existing dotfile installations and an empty or missing database, use `sync` to rebuild it.
+
+##### The Problem: Unwanted Symlinks
 
+By default, `sync` scans your home directory and `~/.config` for **all** symlinks. This can discover symlinks you don't want to track as dotfiles packages, such as:
+- System symlinks in `~/Library/` (macOS)
+- Application symlinks in `/Applications/`
+- IDE or tool-generated symlinks
+- Homebrew-managed symlinks
+
+For example, without filtering you might see:
 ```bash
-# Preview what would be added to database
 +$ dotx sync --dry-run
+✓ Found 44 symlink(s)
+
+Discovered 25 potential package(s):
+  /Users/wolf/dotfiles/bash        # ✓ Want this
+    5 symlink(s)
+  /Users/wolf/dotfiles/vim          # ✓ Want this
+    8 symlink(s)
+  /Users/wolf/Library               # ✗ Don't want this!
+    1 symlink(s)
+  /Applications/Raycast.app/...    # ✗ Don't want this!
+    1 symlink(s)
+```
+
+##### The Solution: `--package-root`
 
-# Interactively rebuild database from filesystem
-+$ dotx sync
-Found 15 symlink(s) in /Users/wolf
+Use `--package-root` to filter packages to **only** those under specific directories. This is **strongly recommended** to avoid tracking unwanted symlinks:
+
+```bash
+# Filter to only your dotfiles directory
++$ dotx sync --dry-run --package-root ~/dotfiles
+✓ Found 44 symlink(s)
+Filtered out 6 symlink(s) not under --package-root
+
+Discovered 3 potential package(s):
+  /Users/wolf/dotfiles/bash
+    5 symlink(s)
+  /Users/wolf/dotfiles/vim
+    8 symlink(s)
+  /Users/wolf/dotfiles/git
+    2 symlink(s)
+```
+
+You can specify multiple roots if your packages are in different locations:
+
+```bash
++$ dotx sync --package-root ~/dotfiles --package-root ~/work/configs
+```
+
+##### Safety Warning
+
+If you run `sync` without `--package-root` and have an empty database, you'll see a warning:
+
+```bash
++$ dotx sync --dry-run
+✓ Found 44 symlink(s)
+⚠ Warning: No --package-root specified and database is empty.
+  Consider using --package-root to filter packages (e.g., --package-root ~/dotfiles)
+```
+
+##### Complete Example
+
+```bash
+# Preview what will be synced (recommended first step)
++$ dotx sync --dry-run --package-root ~/dotfiles
+
+# After reviewing, sync for real
++$ dotx sync --package-root ~/dotfiles
+✓ Found 15 symlink(s)
+Filtered out 0 symlink(s) not under --package-root
 
 Discovered 3 potential package(s):
   /Users/wolf/dotfiles/bash
@@ -265,66 +330,58 @@ Continue? [y/N]: y
 ✓ Recorded 15 installation(s) in database.
 ```
 
-The `sync` command scans your home directory for symlinks and attempts to determine which package they belong to, then rebuilds the database accordingly.
+**Note:** The `sync` command is **additive** - it updates existing entries and adds new ones, but doesn't delete entries for packages not found. This means running sync with `--package-root` won't remove other packages from your database.
 
-### How it works
+##### Cleaning Orphaned Entries with `--clean`
 
-*Documentation to be expanded*
+Over time, your database may accumulate **orphaned entries** - records for symlinks that no longer exist on the filesystem. Use `--clean` to remove these automatically, similar to `git fetch --prune`:
 
-### What's New in v1.1.0
+```bash
+# Preview what would be cleaned
++$ dotx sync --dry-run --clean --package-root ~/dotfiles
+✓ Found 15 symlink(s)
 
-#### Testing and Quality
-- **Comprehensive test coverage**: 77.64% overall (up from 53%)
-- **21 new database command tests**: Full integration testing for `list`, `verify`, `show`, `sync`
-- **Automated coverage tracking**: pytest-cov integration with HTML reports
-- **Bug fix**: Database now correctly stores symlink paths instead of resolved paths
+Would clean orphaned entries:
+  bash: 2 orphaned entry(ies)
+  vim: 1 orphaned entry(ies)
+Would remove 3 orphaned entry(ies).
 
-#### Documentation
-- Added Development section with testing, pre-commit hooks, and integration testing docs
-- Added clean-up instructions for development artifacts
-- Coverage reports available via `open htmlcov/index.html`
+Dry run - no database changes made.
 
-### What's New in v1.0.0
+# Clean for real
++$ dotx sync --clean --package-root ~/dotfiles
+✓ Found 15 symlink(s)
+Filtered out 0 symlink(s) not under --package-root
 
-#### Installation Database
-- **SQLite database** tracks which packages installed which files
-- **New commands**: `list`, `verify`, `show`, `sync` for package management
-- Database location respects `XDG_DATA_HOME` environment variable
-- Export reinstall commands with `dotx list --as-commands` for easy migration
+Discovered 3 potential package(s):
+  /Users/wolf/dotfiles/bash
+    5 symlink(s)
+  ...
 
-#### Improved Ignore System
-- **`.dotxignore` files** replace CLI `-i/--ignore` option (breaking change)
-- Full gitignore-style pattern syntax support
-- Nested `.dotxignore` files in subdirectories
-- Global ignore file at `~/.config/dotx/ignore`
-- Negation patterns (`!important.conf`)
+This will rebuild the database with the discovered installations.
+Continue? [y/N]: y
 
-#### Quality Improvements
-- Pre-commit hooks with ruff, pyrefly, pytest
-- Modern Python type annotations throughout
-- Better logging with loguru
-- Comprehensive code documentation and comments
+✓ Recorded 15 installation(s) in database.
 
-### Migration from older versions
+Cleaning orphaned entries...
+✓ Removed 3 orphaned entry(ies).
+```
 
-**Breaking change in v1.0.0:** The `-i/--ignore` command-line option has been removed in favor of `.dotxignore` files.
+**When to use `--clean`:**
+- After manually removing symlinks
+- After uninstalling packages without using `dotx uninstall`
+- During regular maintenance to keep database accurate
+- When migrating or reorganizing dotfiles
 
-If you were using:
-```bash
-dotx --ignore=README.* --ignore=.mypy_cache install bash
-```
+**Important:** `--clean` removes database entries for files that don't exist. Always preview with `--dry-run` first to ensure you're not removing entries you want to keep.
 
-Now create a `.dotxignore` file in your package:
-```bash
-+$ cat > bash/.dotxignore <<EOF
-README.*
-.mypy_cache
-EOF
+### How it works
 
-+$ dotx install bash
-```
+*Documentation to be expanded*
+
+### Changelog
 
-Or use the global ignore file at `~/.config/dotx/ignore` for patterns that apply to all packages.
+See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
 
 ## Development
 
@@ -395,10 +452,16 @@ This removes:
 
 **Note:** Add `.` at the end (`git clean -fdx .`) to limit cleanup to the current directory only.
 
-### What's next
+### Shell Completions
+
+dotx includes automatic shell completion via Typer:
+
+```bash
+# Install completion for your shell
+dotx --install-completion
+
+# Or show the completion script to customize it
+dotx --show-completion
+```
 
-Potential future enhancements:
-* Support for templates and variable substitution in dotfiles
-* Hooks system for running commands before/after installation
-* Conflict resolution strategies for overlapping packages
-* Shell completions for bash/zsh/fish
+Supports Bash, Zsh, Fish, and PowerShell automatically.

{dotx-2.1.0 → dotx-2.2.1}/README.md

@@ -1,5 +1,7 @@
 ## The Basic Idea
 
+> **Comparing dotfile managers?** See [ALTERNATIVES.md](ALTERNATIVES.md) for a detailed comparison of dotx vs GNU Stow, chezmoi, YADM, dotbot, and others.
+
 ### What `dotx` does; what it's _for_
 #### The problem
 
@@ -213,15 +215,78 @@ Installations:
 
 #### Rebuild database from filesystem
 
-If you have existing dotfile installations and an empty or missing database, use `sync` to rebuild it:
+If you have existing dotfile installations and an empty or missing database, use `sync` to rebuild it.
+
+##### The Problem: Unwanted Symlinks
 
+By default, `sync` scans your home directory and `~/.config` for **all** symlinks. This can discover symlinks you don't want to track as dotfiles packages, such as:
+- System symlinks in `~/Library/` (macOS)
+- Application symlinks in `/Applications/`
+- IDE or tool-generated symlinks
+- Homebrew-managed symlinks
+
+For example, without filtering you might see:
 ```bash
-# Preview what would be added to database
 +$ dotx sync --dry-run
+✓ Found 44 symlink(s)
+
+Discovered 25 potential package(s):
+  /Users/wolf/dotfiles/bash        # ✓ Want this
+    5 symlink(s)
+  /Users/wolf/dotfiles/vim          # ✓ Want this
+    8 symlink(s)
+  /Users/wolf/Library               # ✗ Don't want this!
+    1 symlink(s)
+  /Applications/Raycast.app/...    # ✗ Don't want this!
+    1 symlink(s)
+```
+
+##### The Solution: `--package-root`
 
-# Interactively rebuild database from filesystem
-+$ dotx sync
-Found 15 symlink(s) in /Users/wolf
+Use `--package-root` to filter packages to **only** those under specific directories. This is **strongly recommended** to avoid tracking unwanted symlinks:
+
+```bash
+# Filter to only your dotfiles directory
++$ dotx sync --dry-run --package-root ~/dotfiles
+✓ Found 44 symlink(s)
+Filtered out 6 symlink(s) not under --package-root
+
+Discovered 3 potential package(s):
+  /Users/wolf/dotfiles/bash
+    5 symlink(s)
+  /Users/wolf/dotfiles/vim
+    8 symlink(s)
+  /Users/wolf/dotfiles/git
+    2 symlink(s)
+```
+
+You can specify multiple roots if your packages are in different locations:
+
+```bash
++$ dotx sync --package-root ~/dotfiles --package-root ~/work/configs
+```
+
+##### Safety Warning
+
+If you run `sync` without `--package-root` and have an empty database, you'll see a warning:
+
+```bash
++$ dotx sync --dry-run
+✓ Found 44 symlink(s)
+⚠ Warning: No --package-root specified and database is empty.
+  Consider using --package-root to filter packages (e.g., --package-root ~/dotfiles)
+```
+
+##### Complete Example
+
+```bash
+# Preview what will be synced (recommended first step)
++$ dotx sync --dry-run --package-root ~/dotfiles
+
+# After reviewing, sync for real
++$ dotx sync --package-root ~/dotfiles
+✓ Found 15 symlink(s)
+Filtered out 0 symlink(s) not under --package-root
 
 Discovered 3 potential package(s):
   /Users/wolf/dotfiles/bash
@@ -237,66 +302,58 @@ Continue? [y/N]: y
 ✓ Recorded 15 installation(s) in database.
 ```
 
-The `sync` command scans your home directory for symlinks and attempts to determine which package they belong to, then rebuilds the database accordingly.
+**Note:** The `sync` command is **additive** - it updates existing entries and adds new ones, but doesn't delete entries for packages not found. This means running sync with `--package-root` won't remove other packages from your database.
 
-### How it works
+##### Cleaning Orphaned Entries with `--clean`
 
-*Documentation to be expanded*
+Over time, your database may accumulate **orphaned entries** - records for symlinks that no longer exist on the filesystem. Use `--clean` to remove these automatically, similar to `git fetch --prune`:
 
-### What's New in v1.1.0
+```bash
+# Preview what would be cleaned
++$ dotx sync --dry-run --clean --package-root ~/dotfiles
+✓ Found 15 symlink(s)
 
-#### Testing and Quality
-- **Comprehensive test coverage**: 77.64% overall (up from 53%)
-- **21 new database command tests**: Full integration testing for `list`, `verify`, `show`, `sync`
-- **Automated coverage tracking**: pytest-cov integration with HTML reports
-- **Bug fix**: Database now correctly stores symlink paths instead of resolved paths
+Would clean orphaned entries:
+  bash: 2 orphaned entry(ies)
+  vim: 1 orphaned entry(ies)
+Would remove 3 orphaned entry(ies).
 
-#### Documentation
-- Added Development section with testing, pre-commit hooks, and integration testing docs
-- Added clean-up instructions for development artifacts
-- Coverage reports available via `open htmlcov/index.html`
+Dry run - no database changes made.
 
-### What's New in v1.0.0
+# Clean for real
++$ dotx sync --clean --package-root ~/dotfiles
+✓ Found 15 symlink(s)
+Filtered out 0 symlink(s) not under --package-root
 
-#### Installation Database
-- **SQLite database** tracks which packages installed which files
-- **New commands**: `list`, `verify`, `show`, `sync` for package management
-- Database location respects `XDG_DATA_HOME` environment variable
-- Export reinstall commands with `dotx list --as-commands` for easy migration
+Discovered 3 potential package(s):
+  /Users/wolf/dotfiles/bash
+    5 symlink(s)
+  ...
 
-#### Improved Ignore System
-- **`.dotxignore` files** replace CLI `-i/--ignore` option (breaking change)
-- Full gitignore-style pattern syntax support
-- Nested `.dotxignore` files in subdirectories
-- Global ignore file at `~/.config/dotx/ignore`
-- Negation patterns (`!important.conf`)
+This will rebuild the database with the discovered installations.
+Continue? [y/N]: y
 
-#### Quality Improvements
-- Pre-commit hooks with ruff, pyrefly, pytest
-- Modern Python type annotations throughout
-- Better logging with loguru
-- Comprehensive code documentation and comments
+✓ Recorded 15 installation(s) in database.
 
-### Migration from older versions
+Cleaning orphaned entries...
+✓ Removed 3 orphaned entry(ies).
+```
 
-**Breaking change in v1.0.0:** The `-i/--ignore` command-line option has been removed in favor of `.dotxignore` files.
+**When to use `--clean`:**
+- After manually removing symlinks
+- After uninstalling packages without using `dotx uninstall`
+- During regular maintenance to keep database accurate
+- When migrating or reorganizing dotfiles
 
-If you were using:
-```bash
-dotx --ignore=README.* --ignore=.mypy_cache install bash
-```
+**Important:** `--clean` removes database entries for files that don't exist. Always preview with `--dry-run` first to ensure you're not removing entries you want to keep.
 
-Now create a `.dotxignore` file in your package:
-```bash
-+$ cat > bash/.dotxignore <<EOF
-README.*
-.mypy_cache
-EOF
+### How it works
 
-+$ dotx install bash
-```
+*Documentation to be expanded*
+
+### Changelog
 
-Or use the global ignore file at `~/.config/dotx/ignore` for patterns that apply to all packages.
+See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
 
 ## Development
 
@@ -367,10 +424,16 @@ This removes:
 
 **Note:** Add `.` at the end (`git clean -fdx .`) to limit cleanup to the current directory only.
 
-### What's next
+### Shell Completions
+
+dotx includes automatic shell completion via Typer:
+
+```bash
+# Install completion for your shell
+dotx --install-completion
+
+# Or show the completion script to customize it
+dotx --show-completion
+```
 
-Potential future enhancements:
-* Support for templates and variable substitution in dotfiles
-* Hooks system for running commands before/after installation
-* Conflict resolution strategies for overlapping packages
-* Shell completions for bash/zsh/fish
+Supports Bash, Zsh, Fish, and PowerShell automatically.

{dotx-2.1.0 → dotx-2.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dotx"
-version = "2.1.0"
+version = "2.2.1"
 description = "A command-line tool to install a link-farm to your dotfiles"
 authors = [
     { name = "Wolf", email = "Wolf@zv.cx" }

dotx-2.2.1/src/dotx/cli.py

@@ -0,0 +1,119 @@
+"""
+Command-line interface for dotx.
+
+This module defines the CLI app structure and global options. Individual commands
+are defined in the commands subpackage.
+"""
+
+import sys
+from pathlib import Path
+from typing import Annotated, Optional
+
+import click
+import typer
+from loguru import logger
+
+from dotx import __version__, __homepage__
+from dotx.options import set_option
+
+# Create the Typer app
+app = typer.Typer(
+    help="Manage a link farm: (un)install groups of links from source packages.",
+    no_args_is_help=True,
+    epilog=f"dotx version {__version__} | {__homepage__}",
+)
+
+
+def version_callback(value: bool):
+    """Handle --version flag."""
+    if value:
+        typer.echo(f"dotx version {__version__}")
+        raise typer.Exit()
+
+
+def configure_logging(debug: bool, verbose: bool, log: Optional[Path]):
+    """Configure logging based on CLI options."""
+    logger.remove()  # Remove default handler
+
+    # Determine log level
+    if debug:
+        level = "DEBUG"
+    elif verbose:
+        level = "INFO"
+    else:
+        level = "WARNING"
+
+    # Add handler
+    if log:
+        logger.add(log, level=level)
+    else:
+        logger.add(sys.stderr, level=level)
+
+
+@app.callback()
+def main(
+    ctx: click.Context,
+    debug: Annotated[
+        bool,
+        typer.Option("--debug/--no-debug", help="Enable debug logging"),
+    ] = False,
+    verbose: Annotated[
+        bool,
+        typer.Option("--verbose/--quiet", help="Enable verbose output / suppress output"),
+    ] = False,
+    log: Annotated[
+        Optional[Path],
+        typer.Option(help="Where to write the log (defaults to stderr)"),
+    ] = None,
+    target: Annotated[
+        Optional[Path],
+        typer.Option(
+            help="Where to install (defaults to $HOME)",
+            exists=True,
+            file_okay=False,
+            dir_okay=True,
+            writable=True,
+        ),
+    ] = None,
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run/--no-dry-run", help="Just echo; don't actually (un)install"),
+    ] = False,
+    version: Annotated[
+        Optional[bool],
+        typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version and exit."),
+    ] = None,
+):
+    """
+    Manage a link farm: (un)install groups of links from source packages.
+
+    Global options like --debug, --verbose, and --target apply to all commands.
+    """
+    configure_logging(debug, verbose, log)
+
+    # Store options in context for commands to access
+    ctx.ensure_object(dict)
+    if target:
+        ctx.obj["TARGET"] = target
+        set_option("TARGET", target, ctx)
+
+    # Set global options
+    set_option("DEBUG", debug, ctx)
+    set_option("VERBOSE", verbose, ctx)
+    set_option("DRYRUN", dry_run, ctx)
+
+    if log:
+        set_option("LOG", log, ctx)
+
+
+# Register commands from submodules
+from dotx.commands import install_cmd, uninstall_cmd, database
+
+install_cmd.register_command(app)
+uninstall_cmd.register_command(app)
+database.register_commands(app)
+
+
+def cli():
+    """Entry point for the CLI."""
+    app()

dotx-2.2.1/src/dotx/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI commands for dotx."""