dotx 2.2.0__tar.gz → 3.1.0__tar.gz

dotx-3.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include src/dotx/installed-schema.sql
+include src/dotx/always-create
+include src/dotx/dotxignore

{dotx-2.2.0/src/dotx.egg-info → dotx-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotx
-Version: 2.2.0
+Version: 3.1.0
 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
 
@@ -76,6 +78,8 @@ Commands:
   list       List all installed packages
   verify     Verify installations against filesystem
   show       Show detailed installation information for a package
+  path       Get source path of an installed package
+  which      Find which package owns a target file
   sync       Rebuild database from filesystem (interactive)
 ```
 So if you had a source package (a directory containing files) named `"bash"` containing `"dot-bashrc"` and
@@ -239,6 +243,52 @@ Installations:
 ...
 ```
 
+#### Get package source path
+
+Get the source path of an installed package for composition with other Unix tools:
+
+```bash
++$ dotx path bash
+/Users/wolf/builds/dotfiles/bash
+
+# Compose with other tools
++$ tree $(dotx path bash)
+/Users/wolf/builds/dotfiles/bash
+├── dot-bash_profile
+├── dot-bash_topics.d
+└── dot-bashrc
+
++$ cd $(dotx path vim)
+
++$ ls -la $(dotx path helix)
+```
+
+The command prints the source directory path(s) where package files are located. If a package has files from multiple source directories (like the shells example with subdirectories), all unique paths are printed, one per line.
+
+Exit codes: 0 if package found, 1 if not found.
+
+#### Find which package owns a file
+
+Find which package installed a specific file:
+
+```bash
++$ dotx which ~/.bashrc
+bash
+
++$ dotx which ~/.config/helix/config.toml
+helix
+
+# Compose with other commands
++$ dotx path $(dotx which ~/.vimrc)
+/Users/wolf/builds/dotfiles/vim
+
++$ tree $(dotx path $(dotx which ~/.zshrc))
+```
+
+Simple output (just the package name) for easy composition with other Unix tools.
+
+Exit codes: 0 if file found, 1 if not managed by any package.
+
 #### Rebuild database from filesystem
 
 If you have existing dotfile installations and an empty or missing database, use `sync` to rebuild it.
@@ -330,6 +380,75 @@ Continue? [y/N]: y
 
 **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.
 
+### Shared Directories: How `.config` and Friends Work
+
+When multiple packages need to install files into the same directory (like `~/.config`), that directory must be a **real directory**, not a symlink. Otherwise, only one package could use it.
+
+`dotx` automatically handles this using **always-create patterns** - directories that are always created as real directories instead of being symlinked.
+
+#### Built-in Always-Create Patterns
+
+These directories are automatically created as real directories:
+
+**XDG Base Directories:**
+- `.config` - Application configuration files
+- `.local` - User-local data
+- `.local/share` - User-specific data files
+- `.local/bin` - User-specific executables
+- `.cache` - Non-essential cached data
+
+**Security-Sensitive Directories:**
+- `.ssh` - SSH keys and configuration
+- `.gnupg` - GPG keys and configuration
+
+For example, if you have both a `vim` and `helix` package that install into `.config`:
+
+```bash
++$ tree -L 2 dotfiles/
+dotfiles/
+├── vim/
+│   └── dot-config/
+│       └── nvim/
+└── helix/
+    └── dot-config/
+        └── helix/
+
++$ dotx install vim helix
+
++$ ls -la ~/.config/
+drwxr-xr-x  .config/         # Real directory (not a symlink!)
+lrwxr-xr-x  nvim -> .../vim/dot-config/nvim/
+lrwxr-xr-x  helix -> .../helix/dot-config/helix/
+```
+
+Notice that `.config` itself is a real directory, allowing both packages to install their subdirectories as symlinks within it.
+
+#### Custom Always-Create Patterns (Advanced)
+
+For most users, the built-in patterns are sufficient. However, if you have custom shared directories, you can create `.always-create` files using the same syntax as `.dotxignore`:
+
+**Package-local** (in your package directory):
+```bash
++$ cat > mypackage/.always-create <<EOF
+# Custom shared directory
+.myapp
+EOF
+```
+
+**User-global** (applies to all packages):
+```bash
++$ mkdir -p ~/.config/dotx
++$ cat > ~/.config/dotx/always-create <<EOF
+# My custom shared directories
+.workspace
+.tools
+EOF
+```
+
+Pattern precedence: **built-in → user global → package-local** (later patterns can override earlier ones using `!negation`)
+
+**Note:** Patterns use leading `/` for root-level matching (e.g., `/.config` matches only `.config` at package root, not `subdir/.config`).
+
 ##### Cleaning Orphaned Entries with `--clean`
 
 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`:
@@ -450,10 +569,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.2.0 → dotx-3.1.0}/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
 
@@ -48,6 +50,8 @@ Commands:
   list       List all installed packages
   verify     Verify installations against filesystem
   show       Show detailed installation information for a package
+  path       Get source path of an installed package
+  which      Find which package owns a target file
   sync       Rebuild database from filesystem (interactive)
 ```
 So if you had a source package (a directory containing files) named `"bash"` containing `"dot-bashrc"` and
@@ -211,6 +215,52 @@ Installations:
 ...
 ```
 
+#### Get package source path
+
+Get the source path of an installed package for composition with other Unix tools:
+
+```bash
++$ dotx path bash
+/Users/wolf/builds/dotfiles/bash
+
+# Compose with other tools
++$ tree $(dotx path bash)
+/Users/wolf/builds/dotfiles/bash
+├── dot-bash_profile
+├── dot-bash_topics.d
+└── dot-bashrc
+
++$ cd $(dotx path vim)
+
++$ ls -la $(dotx path helix)
+```
+
+The command prints the source directory path(s) where package files are located. If a package has files from multiple source directories (like the shells example with subdirectories), all unique paths are printed, one per line.
+
+Exit codes: 0 if package found, 1 if not found.
+
+#### Find which package owns a file
+
+Find which package installed a specific file:
+
+```bash
++$ dotx which ~/.bashrc
+bash
+
++$ dotx which ~/.config/helix/config.toml
+helix
+
+# Compose with other commands
++$ dotx path $(dotx which ~/.vimrc)
+/Users/wolf/builds/dotfiles/vim
+
++$ tree $(dotx path $(dotx which ~/.zshrc))
+```
+
+Simple output (just the package name) for easy composition with other Unix tools.
+
+Exit codes: 0 if file found, 1 if not managed by any package.
+
 #### Rebuild database from filesystem
 
 If you have existing dotfile installations and an empty or missing database, use `sync` to rebuild it.
@@ -302,6 +352,75 @@ Continue? [y/N]: y
 
 **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.
 
+### Shared Directories: How `.config` and Friends Work
+
+When multiple packages need to install files into the same directory (like `~/.config`), that directory must be a **real directory**, not a symlink. Otherwise, only one package could use it.
+
+`dotx` automatically handles this using **always-create patterns** - directories that are always created as real directories instead of being symlinked.
+
+#### Built-in Always-Create Patterns
+
+These directories are automatically created as real directories:
+
+**XDG Base Directories:**
+- `.config` - Application configuration files
+- `.local` - User-local data
+- `.local/share` - User-specific data files
+- `.local/bin` - User-specific executables
+- `.cache` - Non-essential cached data
+
+**Security-Sensitive Directories:**
+- `.ssh` - SSH keys and configuration
+- `.gnupg` - GPG keys and configuration
+
+For example, if you have both a `vim` and `helix` package that install into `.config`:
+
+```bash
++$ tree -L 2 dotfiles/
+dotfiles/
+├── vim/
+│   └── dot-config/
+│       └── nvim/
+└── helix/
+    └── dot-config/
+        └── helix/
+
++$ dotx install vim helix
+
++$ ls -la ~/.config/
+drwxr-xr-x  .config/         # Real directory (not a symlink!)
+lrwxr-xr-x  nvim -> .../vim/dot-config/nvim/
+lrwxr-xr-x  helix -> .../helix/dot-config/helix/
+```
+
+Notice that `.config` itself is a real directory, allowing both packages to install their subdirectories as symlinks within it.
+
+#### Custom Always-Create Patterns (Advanced)
+
+For most users, the built-in patterns are sufficient. However, if you have custom shared directories, you can create `.always-create` files using the same syntax as `.dotxignore`:
+
+**Package-local** (in your package directory):
+```bash
++$ cat > mypackage/.always-create <<EOF
+# Custom shared directory
+.myapp
+EOF
+```
+
+**User-global** (applies to all packages):
+```bash
++$ mkdir -p ~/.config/dotx
++$ cat > ~/.config/dotx/always-create <<EOF
+# My custom shared directories
+.workspace
+.tools
+EOF
+```
+
+Pattern precedence: **built-in → user global → package-local** (later patterns can override earlier ones using `!negation`)
+
+**Note:** Patterns use leading `/` for root-level matching (e.g., `/.config` matches only `.config` at package root, not `subdir/.config`).
+
 ##### Cleaning Orphaned Entries with `--clean`
 
 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`:
@@ -422,10 +541,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.2.0 → dotx-3.1.0}/pyproject.toml

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

dotx-3.1.0/src/dotx/always-create

@@ -0,0 +1,23 @@
+# Default patterns for directories that must be created (real directories, never symlinked)
+#
+# These are common shared directories where multiple programs/packages install files.
+# If these were symlinks, only one package could use them.
+#
+# This file is shipped with dotx and can be overridden by:
+#   ~/.config/dotx/always-create (user-specific additions)
+#   <package>/.always-create (package-specific rules)
+#
+# Uses gitignore-style patterns with leading / to match only at root level:
+#   /.config         - match .config at root only (not .config/subdir)
+#   /.local/share    - match .local/share only (not .local/share/applications)
+
+# XDG Base Directory specification directories
+/.config
+/.local
+/.local/share
+/.local/bin
+/.cache
+
+# Other common shared directories
+/.ssh
+/.gnupg

{dotx-2.2.0 → dotx-3.1.0}/src/dotx/cli.py

@@ -107,11 +107,12 @@ def main(
 
 
 # Register commands from submodules
-from dotx.commands import install_cmd, uninstall_cmd, database
+from dotx.commands import install_cmd, uninstall_cmd, database, path_cmd
 
 install_cmd.register_command(app)
 uninstall_cmd.register_command(app)
 database.register_commands(app)
+path_cmd.register_commands(app)
 
 
 def cli():

{dotx-2.2.0 → dotx-3.1.0}/src/dotx/commands/database.py

@@ -1,5 +1,6 @@
 """Database-related commands for dotx CLI (list, verify, show, sync)."""
 
+from datetime import datetime
 from pathlib import Path
 from typing import Annotated, Optional
 
@@ -14,6 +15,23 @@ from dotx.database import InstallationDB
 from dotx.options import is_verbose_mode
 
 
+def _format_timestamp(iso_timestamp: str | None) -> str:
+    """
+    Format an ISO timestamp for display.
+
+    Converts ISO 8601 timestamp to readable format: YYYY-MM-DD HH:MM:SS
+    Returns 'unknown' if timestamp is None or invalid.
+    """
+    if not iso_timestamp:
+        return "unknown"
+
+    try:
+        dt = datetime.fromisoformat(iso_timestamp)
+        return dt.strftime("%Y-%m-%d %H:%M:%S")
+    except (ValueError, AttributeError):
+        return "unknown"
+
+
 def _scan_symlinks(path: Path, max_depth: int, progress: Progress, task_id) -> list[tuple[Path, bool]]:
     """
     Scan a directory for symlinks up to a maximum depth.
@@ -73,7 +91,9 @@ def register_commands(app: typer.Typer):
             if as_commands:
                 # Output as dotx install commands (plain text, no formatting)
                 for pkg in packages:
-                    typer.echo(f"dotx install {pkg['package_name']}")
+                    # Use package_root / package_name to construct install path
+                    package_path = Path(pkg["package_root"]) / pkg["package_name"]
+                    typer.echo(f"dotx install {package_path}")
             else:
                 # Output as rich table
                 table = Table(title="Installed Packages", show_header=True, header_style="bold cyan")
@@ -82,13 +102,9 @@ def register_commands(app: typer.Typer):
                 table.add_column("Last Install", style="green")
 
                 for pkg in packages:
-                    package_name = Path(pkg["package_name"]).name
+                    package_name = pkg["package_name"]  # Already the semantic name
                     file_count = str(pkg["file_count"])
-                    latest = (
-                        pkg["latest_install"][:19]
-                        if pkg["latest_install"]
-                        else "[dim]unknown[/dim]"
-                    )
+                    latest = _format_timestamp(pkg["latest_install"])
                     table.add_row(package_name, file_count, latest)
 
                 console.print()
@@ -117,12 +133,12 @@ def register_commands(app: typer.Typer):
         with InstallationDB() as db:
             if package:
                 # Verify specific package
-                packages_to_verify = [package]
+                packages_to_verify = [(package.parent, package.name)]
             else:
                 # Verify all packages
                 all_packages = db.get_all_packages()
                 packages_to_verify = [
-                    Path(pkg["package_name"]) for pkg in all_packages
+                    (Path(pkg["package_root"]), pkg["package_name"]) for pkg in all_packages
                 ]
 
             if not packages_to_verify:
@@ -130,14 +146,14 @@ def register_commands(app: typer.Typer):
                 return
 
             total_issues = 0
-            for pkg in packages_to_verify:
-                issues = db.verify_installations(pkg)
+            for pkg_root, pkg_name in packages_to_verify:
+                issues = db.verify_installations(pkg_root, pkg_name)
                 if issues:
-                    console.print(f"\n[bold cyan]{pkg.name}:[/bold cyan]")
+                    console.print(f"\n[bold cyan]{pkg_name}:[/bold cyan]")
                     for issue in issues:
-                        console.print(f"  [red]✗[/red] {issue['target_path']}")
-                        console.print(f"    [dim]Issue: {issue['issue']}[/dim]")
-                        console.print(f"    [dim]Expected: {issue['link_type']}[/dim]")
+                        console.print(f"  [red]✗[/red] {issue["target_path"]}")
+                        console.print(f"    [dim]Issue: {issue["issue"]}[/dim]")
+                        console.print(f"    [dim]Expected: {issue["link_type"]}[/dim]")
                     total_issues += len(issues)
 
             if total_issues == 0:
@@ -164,15 +180,19 @@ def register_commands(app: typer.Typer):
         logger.info("show starting")
         console = Console()
 
+        # Extract package info
+        package_root = package.parent
+        package_name = package.name
+
         with InstallationDB() as db:
-            installations = db.get_installations(package)
+            installations = db.get_installations(package_root, package_name)
 
             if not installations:
-                console.print(f"[yellow]No installations found for {package.name}[/yellow]")
+                console.print(f"[yellow]No installations found for {package_name}[/yellow]")
                 return
 
             # Create info panel
-            info = f"[bold cyan]Package:[/bold cyan] {package}\n"
+            info = f"[bold cyan]Package:[/bold cyan] {package_name}\n"
             info += f"[bold cyan]Installed files:[/bold cyan] {len(installations)}"
 
             panel = Panel(info, title="Package Information", border_style="cyan")
@@ -187,9 +207,9 @@ def register_commands(app: typer.Typer):
 
             for install in installations:
                 table.add_row(
-                    str(install['target_path']),
-                    install['link_type'],
-                    install['installed_at'][:19] if install['installed_at'] else "unknown"
+                    str(install["target_path"]),
+                    install["link_type"],
+                    _format_timestamp(install["installed_at"])
                 )
 
             console.print()
@@ -367,11 +387,12 @@ def register_commands(app: typer.Typer):
                     total_would_clean = 0
 
                     for pkg_info in all_packages:
-                        pkg_path = Path(pkg_info["package_name"])
-                        orphaned = db.get_orphaned_entries(pkg_path)
+                        pkg_root = Path(pkg_info["package_root"])
+                        pkg_name = pkg_info["package_name"]
+                        orphaned = db.get_orphaned_entries(pkg_root, pkg_name)
                         if orphaned:
                             total_would_clean += len(orphaned)
-                            console.print(f"  {pkg_path.name}: {len(orphaned)} orphaned entry(ies)")
+                            console.print(f"  {pkg_name}: {len(orphaned)} orphaned entry(ies)")
 
                     if total_would_clean > 0:
                         console.print(f"[yellow]Would remove {total_would_clean} orphaned entry(ies).[/yellow]")
@@ -394,6 +415,10 @@ def register_commands(app: typer.Typer):
             total_recorded = 0
 
             for package_path, links in packages.items():
+                # Extract package info for database
+                package_root = package_path.parent
+                package_name = package_path.name
+
                 for link_path, resolved, is_dir in links:
                     # Determine link type
                     if is_dir:
@@ -402,9 +427,9 @@ def register_commands(app: typer.Typer):
                         link_type = "file"
 
                     # Record in database
-                    db.record_installation(package_path, link_path, link_type)
+                    db.record_installation(package_root, package_name, package_path, link_path, link_type)
                     total_recorded += 1
-                    logger.debug(f"Recorded {link_path} -> {package_path}")
+                    logger.debug(f"Recorded {link_path} -> {package_name}")
 
             console.print(f"\n[green]✓ Recorded {total_recorded} installation(s) in database.[/green]")
 
@@ -415,12 +440,13 @@ def register_commands(app: typer.Typer):
                 total_cleaned = 0
 
                 for pkg_info in all_packages:
-                    pkg_path = Path(pkg_info["package_name"])
-                    cleaned = db.clean_orphaned_entries(pkg_path)
+                    pkg_root = Path(pkg_info["package_root"])
+                    pkg_name = pkg_info["package_name"]
+                    cleaned = db.clean_orphaned_entries(pkg_root, pkg_name)
                     if cleaned > 0:
                         total_cleaned += cleaned
                         if verbose:
-                            console.print(f"  Cleaned {cleaned} orphaned entry(ies) from {pkg_path.name}")
+                            console.print(f"  Cleaned {cleaned} orphaned entry(ies) from {pkg_name}")
 
                 if total_cleaned > 0:
                     console.print(f"[green]✓ Removed {total_cleaned} orphaned entry(ies).[/green]")

dotx-3.1.0/src/dotx/commands/path_cmd.py

@@ -0,0 +1,108 @@
+"""Path and which commands for dotx CLI - query installed packages."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from loguru import logger
+
+from dotx.database import InstallationDB
+
+
+def register_commands(app: typer.Typer):
+    """Register the path command with the Typer app."""
+
+    @app.command()
+    def path(
+        package: Annotated[
+            str,
+            typer.Argument(help="Package name to get path for"),
+        ],
+        package_root: Annotated[
+            Path | None,
+            typer.Option(help="Package root to disambiguate (if package exists in multiple roots)"),
+        ] = None,
+    ):
+        """
+        Print the source path of an installed package.
+
+        Prints the path(s) where the package files are located, one per line.
+        Useful for composition with other tools: tree $(dotx path bash)
+
+        Exit codes:
+          0 - Package found, path(s) printed
+          1 - Package not found
+        """
+        logger.info(f"path command for package: {package}")
+
+        with InstallationDB() as db:
+            # Get all packages
+            all_packages = db.get_all_packages()
+
+            # Filter by package name
+            matching = [
+                pkg
+                for pkg in all_packages
+                if pkg["package_name"] == package
+                and (package_root is None or Path(pkg["package_root"]).resolve() == package_root.resolve())
+            ]
+
+            if not matching:
+                if package_root:
+                    logger.error(f"Package '{package}' not found in package_root {package_root}")
+                else:
+                    logger.error(f"Package '{package}' not found")
+                raise typer.Exit(code=1)
+
+            # For each matching package, get unique source paths
+            for pkg in matching:
+                # Get installations for this package to find source paths
+                installations = db.get_installations(Path(pkg["package_root"]), pkg["package_name"])
+
+                # Collect unique source_package_root values
+                source_roots = sorted(set(install["source_package_root"] for install in installations))
+
+                # Print each unique source root
+                for source_root in source_roots:
+                    typer.echo(source_root)
+
+        logger.info("path command finished")
+
+    @app.command()
+    def which(
+        target_file: Annotated[
+            Path,
+            typer.Argument(help="Target file to find package for"),
+        ],
+    ):
+        """
+        Print the package name that owns a target file.
+
+        Simple output for composition: dotx path $(dotx which ~/.bashrc)
+
+        Exit codes:
+          0 - File found, package name printed
+          1 - File not found in database
+        """
+        logger.info(f"which command for file: {target_file}")
+
+        # Make path absolute for database lookup
+        target_abs = target_file.absolute()
+
+        with InstallationDB() as db:
+            # Query database for this target path
+            # We need to search through all installations to find matching target_path
+            all_packages = db.get_all_packages()
+
+            for pkg in all_packages:
+                installations = db.get_installations(Path(pkg["package_root"]), pkg["package_name"])
+                for install in installations:
+                    if Path(install["target_path"]) == target_abs:
+                        # Found it - print package name and exit
+                        typer.echo(pkg["package_name"])
+                        logger.info("which command finished")
+                        return
+
+            # Not found
+            logger.error(f"File '{target_file}' not managed by any package")
+            raise typer.Exit(code=1)