Metadata-Version: 2.4
Name: elseware-repo-sync
Version: 1.1.0
Summary: Manage a YAML-configured multi-repository development workspace.
Project-URL: Homepage, https://github.com/elsewaretechnology/elseware-repo-sync
Project-URL: Issues, https://github.com/elsewaretechnology/elseware-repo-sync/issues
Project-URL: Repository, https://github.com/elsewaretechnology/elseware-repo-sync
Author: elseware Technology
License-Expression: MIT
License-File: LICENSE
Keywords: cli,git,repository,workspace,yaml
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Software Development :: Version Control :: Git
Requires-Python: >=3.11
Requires-Dist: elseware-py<2,>=1
Requires-Dist: pyyaml<7,>=6.0.2
Provides-Extra: dev
Requires-Dist: build<2,>=1.3; extra == 'dev'
Requires-Dist: mypy<2,>=1.17; extra == 'dev'
Requires-Dist: pytest-cov<7,>=6.2; extra == 'dev'
Requires-Dist: pytest<9,>=8.4; extra == 'dev'
Requires-Dist: ruff<1,>=0.12; extra == 'dev'
Requires-Dist: twine<7,>=6.1; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12.20250516; extra == 'dev'
Description-Content-Type: text/markdown

# elseware-repo-sync

`elseware-repo-sync` is a command-line tool for managing a multi-repository
development workspace from a `workspace.yaml` file.

## Features

- Clone all configured repositories
- Pull repositories with fast-forward-only Git updates
- Display repository branches and working-tree status
- Install npm dependencies for selected repositories
- Run selected development commands concurrently
- Discover `workspace.yaml` from nested workspace directories
- Validate configuration before running workspace commands
- Emit configurable text or JSON diagnostics through `elseware-py`

---

## Requirements

- Python 3.11 or newer
- Git
- npm for dependency installation and the default development command

---

## Installation

Install the latest release with `pipx`:

```bash
pipx install elseware-repo-sync
```

Confirm the installation:

```bash
elseware-repo-sync --version
```

Upgrade to the latest release:

```bash
pipx upgrade elseware-repo-sync
```

Uninstall:

```bash
pipx uninstall elseware-repo-sync
```

---

## Usage

Run commands from the workspace root or any nested directory:

```bash
elseware-repo-sync clone
elseware-repo-sync install
elseware-repo-sync status
elseware-repo-sync pull
elseware-repo-sync dev
```

Use a different workspace or configuration file:

```bash
elseware-repo-sync --workspace /path/to/workspace status
elseware-repo-sync --config /path/to/workspace/workspace.yaml status
```

The tool searches the current directory and its parents for `workspace.yaml`.
An explicit `--config` path takes precedence over automatic discovery.

### Logging

Normal command output and status tables use stdout. Diagnostics and errors use
stderr through the shared `elseware-py` logger.

```bash
elseware-repo-sync \
  --log-level debug \
  --log-format text \
  --log-color auto \
  status
```

Available values:

- `--log-level`: `debug`, `info`, `warning`, `error`, or `critical`
- `--log-format`: `text` or newline-delimited `json`
- `--log-color`: `auto`, `always`, or `never`

The corresponding environment variables are:

```text
ELSEWARE_REPO_SYNC_LOG_LEVEL
ELSEWARE_REPO_SYNC_LOG_FORMAT
ELSEWARE_REPO_SYNC_LOG_COLOR
```

Command-line options override environment variables. Defaults are `warning`,
`text`, and `auto`.

---

## Workspace Configuration

Create `workspace.yaml` in the workspace root:

```yaml
groups:
  libraries:
    - name: example-ui
      path: libraries/example-ui
      url: https://github.com/example/example-ui.git
      branch: main
      install: true
      dev: false

  services:
    - name: example-service
      path: services/example-service
      url: https://github.com/example/example-service.git
      branch: main
      install: true
      dev: true
      devCommand: npm run dev
```

Required repository fields:

- `name`: unique repository name
- `path`: unique path relative to the workspace
- `url`: Git clone URL

Optional fields:

- `branch`: defaults to `main`
- `install`: defaults to `false`
- `dev`: defaults to `false`
- `devCommand`: defaults to `npm run dev`

Repository paths must remain within the workspace.

---

## Development Setup

Clone the repository:

```bash
git clone https://github.com/elsewaretechnology/elseware-repo-sync.git
cd elseware-repo-sync
```

Create a virtual environment:

```bash
python3 -m venv .venv
```

Activate it on macOS or Linux:

```bash
source .venv/bin/activate
```

Activate it on Windows:

```bash
.venv\Scripts\activate
```

Install the package and development tools:

```bash
python -m pip install --editable ".[dev]"
```

When developing both workspace projects before publishing `elseware-py`,
install the local library first:

```bash
python -m pip install --editable ../../libs/elseware-py
python -m pip install --editable ".[dev]"
```

Run the development version:

```bash
elseware-repo-sync --help
python -m elseware_repo_sync --help
```

Run code-quality checks:

```bash
ruff check .
ruff format --check .
mypy
```

Run tests:

```bash
pytest --cov --cov-report=term-missing
```

---

## Build Package

Remove previous files from `dist/`, then build the wheel and source
distribution:

```bash
python -m build
```

Validate the generated distributions:

```bash
twine check --strict dist/*
```

The build produces:

```text
dist/elseware_repo_sync-<version>-py3-none-any.whl
dist/elseware_repo_sync-<version>.tar.gz
```

---

## Publish to PyPI

Upload the validated wheel and source distribution manually:

```bash
twine upload dist/*
```

When using a PyPI API token:

- Username: `__token__`
- Password: the complete token, including the `pypi-` prefix

The PyPI account must own or maintain the `elseware-repo-sync` project.
Credentials must not be committed to the repository.

---

## Release a New Version

1. Update `version` in `pyproject.toml`.
2. Update `__version__` in `src/elseware_repo_sync/__init__.py` to the same
   value.
3. Run the quality checks and tests.
4. Remove old files from `dist/`.
5. Build and validate the distributions:

   ```bash
   python -m build
   twine check --strict dist/*
   ```

6. Upload the release:

   ```bash
   twine upload dist/*
   ```

7. Tag the published version:

   ```bash
   git tag -a v1.1.0 -m "Release 1.1.0"
   git push origin v1.1.0
   ```

8. Upgrade and verify the installed release:

   ```bash
   pipx upgrade elseware-repo-sync
   elseware-repo-sync --version
   ```

PyPI release files cannot be replaced. Increment the version before publishing
a corrected release.

---

## License

MIT License
