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:

pipx install elseware-repo-sync

Confirm the installation:

elseware-repo-sync --version

Upgrade to the latest release:

pipx upgrade elseware-repo-sync

Uninstall:

pipx uninstall elseware-repo-sync

---

Usage

Run commands from the workspace root or any nested directory:

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:

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.

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:

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:

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:

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

Create a virtual environment:

python3 -m venv .venv

Activate it on macOS or Linux:

source .venv/bin/activate

Activate it on Windows:

.venv\Scripts\activate

Install the package and development tools:

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

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

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

Run the development version:

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

Run code-quality checks:

ruff check .
ruff format --check .
mypy

Run tests:

pytest --cov --cov-report=term-missing

---

Build Package

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

python -m build

Validate the generated distributions:

twine check --strict dist/*

The build produces:

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:

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:

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

6. Upload the release:

   twine upload dist/*
   

7. Tag the published version:

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

8. Upgrade and verify the installed release:

   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