Metadata-Version: 2.4
Name: wdsync
Version: 0.3.0
Summary: Mirror dirty files from a Windows Git repo into a matching WSL repo.
Project-URL: Homepage, https://github.com/EphremTil17/wdsync
Project-URL: Repository, https://github.com/EphremTil17/wdsync
Project-URL: Issues, https://github.com/EphremTil17/wdsync/issues
Project-URL: Changelog, https://github.com/EphremTil17/wdsync/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/EphremTil17/wdsync#readme
Author-email: "Ephrem T." <ephtilahun21@gmail.com>
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: cli,git,rsync,sync,windows,wsl
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: typer<1.0,>=0.24.1
Description-Content-Type: text/markdown

# wdsync

`wdsync` is a WSL-side Python CLI for mirroring the dirty working tree of a
Windows Git repository into a matching WSL repository without requiring a
commit, push, or pull cycle.

It is built for the workflow where:

- your primary editing happens to be on Windows for whatever reason (Flutter, VS Studio, .NET development, etc.)
- your backend, scripts, containers, or Linux tooling run in WSL either for prod or testing parity
- you want the WSL repo to mirror the current Windows dirty-set (staged and unstaged changes) on demand

The key design choice is that `wdsync` reads the source repo with `git.exe`, so
the sync set matches what Git for Windows considers dirty rather than what
Linux Git thinks about `/mnt/c/...`.

## What It Does

From inside a destination WSL repo, `wdsync` will:

- read a local `.wdsync` file
- resolve the Windows source repo from `SRC=/mnt/c/...`
- query the source dirty set using `git.exe` (Windows Git)
- preview by default to see the planned dirty set in the destination WSL repo
- sync when you run `wdsync sync` or `wdsync -f`
- warn with `wdsync doctor` when source and destination `HEAD` differ or the destination repo is already dirty

> Note:
> It includes tracked unstaged files, tracked staged files, and untracked files,
> including nested files in untracked directories. Deleted files detected in the
> source are propagated to the destination (removed from the WSL repo). If a
> deletion fails due to permissions, `wdsync` prompts to retry with `sudo`. Files
> with local changes in the destination are never deleted. It does not yet do
> patch-apply checks, staging/index mirroring, or global config.

## Prerequisites

Get `git` available in WSL and Windows (`git.exe`), plus `rsync`, `wslpath`,
Python 3.11+, and either `uv` or `pip`; the source repo must be reachable as
`/mnt/<drive>/...`.

## Install

- [Read the detailed Setup guide here](./SETUP.md) | Recommended install path:

```bash
uv tool install wdsync
```

Alternative install path with `pip` after python venv:

```bash
python -m pip install wdsync
```

## Per-Project Config

Each destination WSL repo gets a local `.wdsync` file at the repo root:

```ini
SRC=/mnt/c/Users/YourName/path/to/WindowsRepo
```

Example:

```ini
SRC=/mnt/c/Users/<User>/Documents/Projects/<ProjectName>
```

`wdsync init` writes this file for you and adds `.wdsync` to the destination
repo's `.git/info/exclude` so it stays local.

## Quick Start

From inside the destination WSL repo:

```bash
wdsync init /mnt/c/Users/YourName/path/to/WindowsRepo
wdsync
wdsync sync
```

Doctor mode: Explain potential sync risks from source and destination state:

```bash
wdsync doctor
```

If you want to contribute or work on the codebase itself, use:

- [DEVELOPER_SETUP](./docs/DEVELOPER_SETUP.md) for contributor environment setup

Additional references:

- [CHANGELOG](./CHANGELOG.md) for release history

## Project Layout

```text
wdsync/
├── docs/
├── src/ [config, doctor, preview, shell, sync, sync, runner ...]
│   └── wdsync/
├── scripts/
│   ├── bash/
│   └── fish/
└── tests/
```

## Commands

| Command                | JSON Output                       | Purpose                                                          |
| ---------------------- | --------------------------------- | ---------------------------------------------------------------- |
| `wdsync`               | Yes, with `wdsync --json`         | Preview the current source dirty set.                            |
| `wdsync preview`       | Yes, with `wdsync preview --json` | Explicit preview mode.                                           |
| `wdsync sync`          | Yes, with `wdsync sync --json`    | Copy the planned dirty files into the current WSL repo.          |
| `wdsync init <SRC>`    | No                                | Create `.wdsync` for the current destination repo.               |
| `wdsync doctor`        | Yes, with `wdsync doctor --json`  | Show advisory sync-risk checks for source and destination state. |
| `wdsync shell install` | No                                | Install optional shell helpers and completions.                  |

## Git Status Labels Passed

| `[unstaged] [ M]` | `[staged] [M ]` | `[both] [MM]` | `[new] [??]` | `[added] [A ]` | `[added+mod] [AM]` | `[renamed] [R ]` | `[copied] [C ]` | `[deleted] [ D]` | fallback `[changed]` |

## Shell Integration

The CLI itself is shell-agnostic once installed. Optional shell helpers can be
installed with:

```bash
wdsync shell install
```

Override shell detection when needed:

```bash
wdsync shell install --shell fish
wdsync shell install --shell bash
wdsync shell install --shell zsh
```

What `shell install` does:

- auto-detects `fish`, `bash`, or `zsh`
- installs completion assets
- installs a `wdsync-init` helper wrapper
- installs fish function delegates when using fish

The `scripts/` directory contains thin repo-local wrapper examples that
delegate to the installed CLI or fall back to `uv run`.

- `scripts/bash/` contains executable shell wrappers
- `scripts/fish/` contains fish functions
- the bash wrappers also work fine as standalone executable helpers from zsh

## Important Behavior Notes

Source dirty-file detection comes from `git.exe`, not Linux Git. Preview shows
the full source dirty set rather than a destination diff, and sync copies file
contents only. A source staged file does not remain staged in the destination
repo. Deleted files are propagated to the destination: if a file was deleted in
the Windows source, `wdsync sync` removes it from the WSL repo. Files that have
local changes in the destination are skipped to avoid destroying local work. If
a deletion fails due to file permissions, `wdsync` will prompt to retry with
`sudo`. Renames and copies are parsed correctly from porcelain v1 `-z` and
untracked directories are expanded to leaf file paths.

## Limitations

`wdsync` is WSL-only, supports one source path per destination repo, and
expects the source path to live under `/mnt/<drive>/...`. It does not yet run
patch-apply checks or support post-sync hooks.

See [IN_DEVELOPMENT.md](docs/IN_DEVELOPMENT.md) for the roadmap beyond the current
Python CLI baseline.
