dploy 0.1.3__tar.gz → 0.2.0rc1__tar.gz

dploy-0.2.0rc1/.gitattributes

@@ -0,0 +1,5 @@
+# This checkout is shared between Windows and Linux (via Dropbox), so the same
+# physical files are opened by both. Normalize to LF everywhere -- including in
+# the working tree on Windows -- so that editing from one side does not rewrite
+# every file from the other side's point of view.
+* text=auto eol=lf

dploy-0.2.0rc1/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs reads the version from tags, so it needs the full history.
+          fetch-depth: 0
+
+      - name: Enable symlinks on Windows
+        if: runner.os == 'Windows'
+        run: |
+          reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock" /t REG_DWORD /v "AllowDevelopmentWithoutDevLicense" /d 1 /f
+          git config --global core.symlinks true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Lint (pylint, ruff, ty)
+        run: uv run invoke lint
+
+      - name: Reformat Check (ruff)
+        run: uv run invoke reformat-check
+
+      - name: Metrics (radon)
+        run: uv run invoke metrics
+
+      - name: Test (pytest)
+        run: uv run invoke test

dploy-0.2.0rc1/.github/workflows/release.yaml

@@ -0,0 +1,50 @@
+name: Release
+
+# Publishes to PyPI when a version tag is pushed, for example:
+#   git tag 0.2.0 && git push origin 0.2.0
+# The package version comes from the tag (hatch-vcs), so there is no version
+# to edit by hand. Before tagging, set the date in CHANGELOG.md.
+#
+# One-time setup on PyPI: add this repository and workflow (release.yaml) as a
+# trusted publisher for the project, with the environment name "pypi".
+
+on:
+  push:
+    tags:
+      - "[0-9]+.[0-9]+.[0-9]+*"
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs reads the version from tags, so it needs the full history.
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

dploy-0.2.0rc1/.gitignore

@@ -0,0 +1,16 @@
+# python files
+__pycache__/
+*.pyc
+.venv/
+
+# pyinstaller files
+dist/
+build/
+*.spec
+
+# pytest-cov files
+.coverage
+.pytest_cache/
+
+# git worktrees
+.worktree/

dploy-0.2.0rc1/AGENTS.md

@@ -0,0 +1,21 @@
+# dploy
+
+A command-line stow/link/unstow utility for managing dotfiles and other
+symlinked file trees.
+
+## Agent skills
+
+### Issue tracker
+
+Issues live as GitHub issues in `arecarn/dploy`, managed with the `gh` CLI. See
+`docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Default canonical role names (`needs-triage`, `needs-info`, `ready-for-agent`,
+`ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: `CONTEXT.md` and `docs/adr/` at the repo root (created lazily,
+absence is not an error). See `docs/agents/domain.md`.

dploy-0.2.0rc1/CHANGELOG.md

@@ -0,0 +1,233 @@
+# Change Log
+
+The format of this change log is based on [Keep a Changelog](http://keepachangelog.com/)
+
+All changes documented here should be written with the goal give the end-user
+(not other developers) a summarized view of the changes since the last release,
+organized by order of importance.
+
+## [0.2.0] - Unreleased
+
+### Added
+
+- Added a `--skip-conflicts` flag to `stow` that links everything that
+  doesn't conflict with an existing, unmanaged file instead of aborting the
+  whole command. Dploy exits with status `2` when some files were skipped.
+- Added a `--no-folding` flag to `stow` and `unstow`, matching GNU Stow's
+  flag of the same name, that keeps each file as its own individual link
+  instead of folding a destination directory into one link.
+- Added a `--dotfiles` flag to `stow` and `unstow`, matching GNU Stow's flag
+  of the same name: a package entry named `dot-foo` is linked as `.foo`.
+  `unstow` removes links by what they point at, so it does not need the flag.
+
+### Changed
+
+- **Breaking:** Renamed `source`/`sources`/`dest` to `package`/`packages`/
+  `destination` across the public API and the CLI, to match the terms
+  `CONTEXT.md` defines. This affects the `stow`, `unstow`, and `clean`
+  function parameters and CLI arguments. The `link` command's argument stays
+  `source`, since it takes a single file or directory, not a package.
+- Switch to uv for dependency management instead of Poetry.
+- Use hatchling as the build system.
+- Switch CI from Travis CI and AppVeyor to GitHub Actions.
+- Move Pylint configuration to pyproject.toml and remove in-code suppressions.
+
+### Fixed
+
+- On Windows, a link to a directory is now created as a directory symlink
+  instead of a file symlink, which did not work.
+- On Windows, existing links are now recognized as pointing at their
+  package. Windows reports link targets with a `\\?\` prefix, which made
+  every comparison with the package path fail.
+- On Windows, dploy now decides whether two paths are the same file by asking
+  the file system instead of comparing path text, so a different spelling of
+  one path (letter case, short names) no longer counts as a different file.
+- An ignore pattern the file system rejects, which Windows does for some
+  patterns POSIX accepts, is now skipped instead of crashing stow, unstow
+  and clean.
+- On Windows, permission checks now read the file's ACL instead of only the
+  read-only flag, so an unreadable or unwritable path is reported before
+  anything changes rather than raising `PermissionError` part way through.
+- Blank lines in `.dploystowignore`, or an empty `--ignore` pattern, no
+  longer crash stow/unstow/clean.
+- Stowing a second package that shares a directory two or more levels deep
+  with an already-stowed package no longer writes into the first package's
+  source tree.
+- Recursive ignore patterns, like `**/*.swp`, no longer cause dploy to skip
+  the whole folder a matching file lives in, including when that folder is
+  shared with another package being stowed.
+- `unstow` no longer leaves behind an empty directory when all of its
+  contents are removed within the same run, for example a subdirectory
+  cleared while its parent directory only contained that one entry.
+- `clean` now removes dangling links. It previously removed nothing, because
+  it could not match a link to its package unless the package sat directly in
+  the working directory and the link's target had no `..` in it. An unreadable
+  directory is now reported as an error instead of crashing.
+- `link` now reports a clean error when the destination's parent is a file
+  instead of a directory. It previously crashed with a traceback.
+
+## [0.1.3] - 2026-02-13
+
+### Added
+
+- Added a `dploy clean` subcommand.
+
+### Changed
+
+- Switch to Poetry for packaging instead of setuptools.
+- Require at least Python >= 3.10.
+- Use black for auto formatting instead of yapf.
+- Use custom *DployError* exceptions.
+- Version is now sourced from pyproject.toml via importlib.metadata.
+
+### Fixed
+
+- Print syntax help if no valid subcommand was provided.
+- Fixed pytest.
+- Fixed invoke tasks to work with Poetry and Python 3.13.
+
+### Removed
+
+- Removed requirements.txt in favor of pyproject.toml dependency groups.
+
+## [0.1.2] - 2017-10-26
+
+### Changed
+
+- Renamed the CLI --quiet option to --silent because it better reflects the
+  effect of the option
+
+### Fixed
+
+- Fix bug causing unstow to delete dest directory when unfolding.
+  When unstowing and nearly all actions have been collected additional checking
+  to find candidates for folding i.e. when a directory contains symlinks to
+  files that all share the same parent directory. It just so happens that the
+  dest directory passed into unstow could also meet this same criteria and would
+  be deleted in error.
+
+- Produce a helpful error when stowing or unstowing with duplicate sources.
+  Before stow would fail, when conflicts were found, and unstow would succeed in
+  unstowing a duplicate source the first time, but fail after trying to unstow
+  nothing. By catching the bug before hand the error message is much clearer.
+
+- Fix bug stowing or linking paths that cannot be relative to each other and
+  caused a silent failure.
+  e.g. with windows paths: `dploy stow C:\some\path D:\other\Path`
+  Since the symbolic links can't use a relative path fallback to the absolute
+  version of the path passed in.
+
+## [0.1.1] - 2016-12-29
+
+### Fix
+
+- Added a MANIFEST.in to fix installation via PyPi
+
+## [0.1.0] - 2016-12-29
+
+### Changed
+
+- Added Dates to Change log releases
+
+### Fixed
+
+- Fixed change log formatting
+- Fix PyPi Package so it can be installed
+
+## [0.0.5] - 2016-12-28
+
+### Added
+
+- Added --ignore argument to stow and unstow commands, to specify patterns file
+  to ignore.
+- Added reading of .dploystowignore files in the directories of sources for
+  ignore patterns that are additional to those specified via --ignore
+- Added optional is_silent & is_dry_run arguments to dploy.stow() dploy.unstow()
+  and dploy.link(), This is analogous to the --dry-run and --quiet command line
+  arguments. These function arguments default to is_silent=True and
+  is_dry_run=False.
+- Added redundant check to make sure dploy never deletes anything other than a
+  symbolic link
+- Check for source and dest new consideration was taken for sources
+  and dests directories that have invalid execute permissions.
+
+### Changed
+
+- Check for additional issues with sub commands that are similar to the initial
+  checks done on the input of stow and unstow
+- Prevent redundant errors when the src or dest are not directories
+- Clarify some error messages
+- Display the user inputted source and dest paths instead of absolute paths in
+  the output
+- Clarify error messages for file and symbolic link conflicts
+- Make the output of dploy stow and unstow deterministic across file systems
+- Changed the output of failing dploy sub commands so they print as many
+  detected issues as possible before aborting
+- Print all conflicts while stowing instead of just the first conflict, and
+  print what exactly the conflict is
+
+### Fixed
+
+- Fixed issue when unstowing where some stowed packages directories created
+  during the stowing process via unfolding would not be deleted.
+- Fix issue unstowing a folded dir with a stray link
+  - This fixed the following scenario: Given a dest directory with stowed
+    packages that share a folded directory, that also contains a stray link
+    along with the links created by stowing. When the stowed packages are
+    unstowed Then the folded directory was re-folded using the parent
+    directory of the single stray link and possibly linking new files that
+    were never intended to be linked there. When what was desired was the
+    directory to just remain with the single stray symlink.
+- Fix an improperly handled expetion that occurred when unstowing a package that
+  had it's destination directories execute permission unset.
+
+## [0.0.4] - 2016-09-13
+
+### Added
+
+- Add folding of the remaining links that would be around after calling unstow
+- Add Checks for conflicts between multiple sources for stow
+- Add checking to see if args are directories for stow and unstow
+- Add check the permissions for source and dest before running a command
+- Add error handling for source permissions errors for stow and unstow
+- CLI: Add a --dry-run flag to show what would be done
+- CLI: Add a --quiet option to suppress normal output
+- CLI: Add handling for canceling the program with CTRL-C
+- CLI: Add a message for case when a source is already unlinked
+
+### Changed
+
+- Relicense under MIT
+- Make dploy module usage silent
+- Clarify message when a source argument is the same the dest argument
+- Have the dploy module throw exceptions that the CLI module would handle
+  instead of just printing to stdout
+
+### Fixed
+
+- CLI: Fix link to take only take one source
+- Fix link source arg so it takes a string not a list
+- Fix console output to print the correct command name e.g. stow, link, and
+  unstow
+- Fix issue where files could be deleted during unstow folding
+- Fix bug that would cause an unexpected and unhanded exception when there was
+  link in the destination directory that pointed to a non existing location in
+  the source.
+- Fix issue in stow and unstow where source and dest could be the same. This
+  issue made it possible to delete files when unstow had the same
+  parameters for both source and dest. It also didn't make sense to try to stow
+  a directory into itself, since there will always be conflicts.
+
+## [0.0.3] - 2016-04-11
+
+### Added
+
+- Adds support for python 3.3
+- Add an unstow command to undo stowing
+
+### Changed
+
+- Stow command is run in two passes and check for conflicts first before making
+  any changes
+
+- General bug fixes and improvements.

dploy-0.2.0rc1/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

dploy-0.2.0rc1/CONTEXT.md

@@ -0,0 +1,105 @@
+# dploy
+
+dploy creates and removes symbolic links so that the contents of one directory
+appear inside another, in the manner of GNU Stow, on Windows, Linux, and macOS.
+
+## Language
+
+### What gets linked
+
+**Package**:
+A directory whose contents are linked into a destination as a unit. Packages are
+always named explicitly on the command line; dploy has no directory it searches
+for them.
+_Avoid_: source, source directory, stow package
+
+**Destination**:
+The directory a package's contents are linked into.
+_Avoid_: target, target directory, dest
+
+**Target**:
+The path a symbolic link points at. A link's target is what it refers to, never
+where it lives.
+_Avoid_: referent, linked-to path
+
+**Dangling link**:
+A symbolic link whose target no longer exists.
+_Avoid_: broken link, orphaned link, stale link
+
+### Dot-file names
+
+**Dotfile translation**:
+With `--dotfiles`, linking a package entry named `dot-foo` under the destination
+name `.foo`. A name where `dot-` is followed by nothing or by a dot is never
+translated.
+_Avoid_: dot renaming, dot expansion
+
+**Literal name**:
+A package entry's own name, such as `dot-foo`.
+_Avoid_: original name, source name
+
+**Translated name**:
+The name dotfile translation gives an entry, such as `.foo`. For an entry that is
+not translated, it is the same as the literal name.
+_Avoid_: dot name, renamed name
+
+**Matching by target**:
+How unstow finds the links to remove: a link is removed because its target is
+inside the package, whichever of the entry's two names it carries. A file or link
+that does not point into the package is never touched.
+_Avoid_: name matching, flag matching
+
+### Operations
+
+**Stow**:
+Linking the contents of a package into a destination. Stowing is idempotent:
+stowing an already-stowed package reports the links as already in place.
+_Avoid_: install, deploy, apply
+
+**Unstow**:
+Removing the links a stow produced, recognised by their target rather than by
+their name. Also idempotent.
+_Avoid_: uninstall, remove, undeploy
+
+**Clean**:
+Removing dangling links in a destination that point into a given package. Unlike
+unstow, it acts on links whose targets are already gone.
+_Avoid_: prune, sweep, garbage collect
+
+**Link**:
+Creating a single symbolic link at an exact path, rather than linking a whole
+package's contents. Where the distinction matters, say "the link command" for
+the operation and "a symbolic link" for the thing.
+_Avoid_: symlink (as the name of the operation)
+
+**Folding**:
+Replacing a destination directory whose links all point into one package
+directory with a single link to that directory.
+_Avoid_: collapsing, compacting
+
+**Unfolding**:
+Replacing a link to a directory with a real directory containing links to that
+directory's contents, so a second package can contribute entries alongside the
+first.
+_Avoid_: expanding, exploding
+
+### How work is described
+
+**Action**:
+A single filesystem change dploy intends to make: creating a link, removing a
+link, creating a directory, removing a directory. Actions are collected and
+validated as a set before any of them run, so a command either applies fully or
+not at all.
+_Avoid_: operation, step, task, change
+
+**Conflict**:
+A reason a collected set of actions cannot be applied, such as a destination
+entry that is not a link dploy created, or two packages claiming the same
+destination path. Conflicts are reported together and abort the command before
+any action runs.
+_Avoid_: error, clash, collision
+
+**Ignore pattern**:
+A glob that excludes matching entries of a package from being linked. Patterns
+come from the command line or from a `.dploystowignore` file beside the package.
+_Avoid_: exclude pattern, skip pattern, filter

dploy-0.2.0rc1/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.5
+Name: dploy
+Version: 0.2.0rc1
+Summary: Provides functionality similar to GNU Stow as a cross platform CLI tool and Python 3 module
+Project-URL: Homepage, https://github.com/arecarn/dploy
+Author-email: Ryan Carney <arecarn@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Dploy
+
+Dploy is a tool for creating symbolic links similarly to [GNU
+Stow](https://www.gnu.org/software/stow/). It is provided as a CLI tool and
+Python 3.10+ module and supports Windows, Linux, and OSX.
+
+Dploy's command `stow` creates symbolic links to the contents of packages in a
+specified destination directory. Repeating the
+`stow` command with the same arguments will confirm that the contents of the
+package have been symbolically linked.
+
+Dploy's command `unstow` removes symbolic links that resulted from `stow`
+commands. Repeating the `unstow` command with the same arguments will confirm
+that the links to stowed packages have been removed.
+
+## Installation
+
+* Latest Release: `pip install dploy`
+* Development Version: `pip install git+https://github.com/arecarn/dploy.git`
+
+## Basic CLI Usage
+
+* `dploy stow <package-directory>... <destination-directory>`
+* `dploy unstow <package-directory>... <destination-directory>`
+* `dploy clean <package-directory>... <destination-directory>`
+* `dploy --help`
+
+### Dot-file names
+
+`stow --dotfiles` stows a package entry named `dot-something` as a destination
+entry named `.something`:
+
+```
+dploy stow --dotfiles ~/dotfiles/bash ~
+# ~/dotfiles/bash/dot-bashrc  ->  ~/.bashrc
+```
+
+This keeps the files visible in the package directory while they land as
+dot-files in the destination.
+
+`unstow` does not need `--dotfiles`. It finds links by what they point at, so it
+removes them whether they are named `dot-something` or `.something`. It still
+accepts the flag, for symmetry with `stow`; with it, an unrelated file already
+named `.something` is reported as a conflict. `clean` is unaffected for the
+same reason.
+
+An entry whose name is `dot-` followed by nothing or by a dot (`dot-`,
+`dot-.`, `dot-..`, `dot-.hidden`) is left untranslated, as GNU Stow does; the
+first two would otherwise resolve to the destination directory or its parent.
+
+## Rationale
+
+Dploy started out as simple Python script to create symbolic links to my
+dotfiles for Windows, Mac, and Linux. Over time I keep improving and tweaking my
+script to suit my needs, but I was running into a problem.  Keeping all the
+files I wanted to link in a config file was becoming a real pain in the neck.
+
+I started looking for another solution to solve my problem, and found many
+alternatives but none of them seemed to be a good fit. The solution that seemed
+the most promising was using GNU Stow. It seemed like the most simple elegant
+solution to the problem. The only issue was that it didn't support Windows.
+
+Then I thought to myself, why can't I just create my own version of Stow that
+work on Windows, Linux and OSX. So after that my I started morphing
+simple python script into what would become Dploy and learned a lot more about
+python in the process.
+
+## How does it compare with GNU Stow?
+
+Below are just a few few major points of comparison between GNU stow and Dploy.
+
+* Like GNU Stow Dploy runs in two passes. First by collecting the actions
+  required to complete the command and verifying that the command can
+  completed without any issues. If no issues are detected then the second
+  pass executes these actions are execute to complete the command. Otherwise
+  Dploy will exit and indicate why the command can not be completed. This way a
+  stow or unstow operation is atomic and never partially done.
+
+* Like Stow, Dploy supports tree folding and tree unfolding. Like Stow's
+  `--no-folding`, passing `--no-folding` to `stow` or `unstow` disables
+  folding, so each file gets its own link inside a real directory.
+
+* Unlike Stow, Dploy requires an explicit package(s) and a destination
+  directory.
+
+* Unlike Stow, Dploy does not have any concept of ownership, but will only
+  operate on symbolic links and the creation or removal of directories for these
+  symbolic links.
+
+* Unlike Stow, Dploy's `unstow` removes a destination directory that becomes
+  empty as a result of removing its symbolic links, even if that directory
+  existed before `stow` created any links inside it. Dploy keeps no state
+  across invocations, so it cannot distinguish a directory it created from
+  one that already existed.
+
+* `stow`'s `--skip-conflicts` flag is the one opt-in exception to the
+  atomicity described above: files that conflict with an existing,
+  unmanaged destination entry are skipped and reported, while every other
+  file in the package is still linked. `dploy` exits with status `2` when
+  this happens, so a script can tell a partial stow apart from a full
+  success (status `0`) or a fatal error (status `1`).