Installation and First Workflow

🚀Installation and First Workflow

Recommended

Install Reflow in an isolated environment and preview a local tag-conversion plan against an explicit target.

Commandreflow

📦Category

Getting Started

🚀Quick Command

reflow --dry-run -C /path/to/project tags convert local

---

ℹ️Runtime requirement

Reflow requires Python 3.14 or newer. Keep the Reflow installation separate from the repository it will operate on; target the repository explicitly when the current directory is ambiguous.

Install from the Private GitLab Registry

Reviewed releases are published as private Python packages in the project's GitLab PyPI registry. Ask a maintainer for the GitLab project ID and a deploy token limited to read_package_registry.

Install an authorized package version

bash

python -m venv venv

# Activate the environment, then install one reviewed package version.

python -m pip install --index-url "https://<deploy-user>:<deploy-token>@gitlab.com/api/v4/projects/<project-id>/packages/pypi/simple" "git-reflow==1.0.2"

reflow --version

⚠️Package name and command name differ

Use git-reflow in pip. The installed command is reflow. A Git tag such as v1.0.0-rc.1 is published with the canonical PEP 440 package version 1.0.0rc1, so an authorized RC installation uses git-reflow==1.0.0rc1.

This is a private registry, not public PyPI. Never commit a token or a credential-bearing index URL. The source-checkout method below remains valid when private-registry access is unavailable.

Install from a Reviewed Source Checkout

Create an isolated environment

bash

python -m venv venv

# Activate with the command for your shell:

# Windows PowerShell: .\venv\Scripts\Activate.ps1

# POSIX shell: source venv/bin/activate

python -m pip install .
reflow --version

🕒First Local Workflow

1

Select a checkout

Use -C/--repository so the Reflow source checkout cannot become the accidental target.

current

2

Initialize configuration

Generate .config/reflow/config.toml and review it before sharing or editing defaults.

pending

3

Inspect tags

Use Git to confirm which existing tag names the conversion plan should consider.

pending

4

Preview conversion

Run the local conversion with global --dry-run and inspect every source-to-destination mapping.

pending

5

Choose whether to execute

A live run changes only local tag refs; it does not push them.

pending

Initialize and preview

bash

reflow -C /path/to/project init
git -C /path/to/project tag --list
reflow --dry-run -C /path/to/project tags convert local --to semver

⚠️Do not add --yes until the plan is understood

Dry-run never prompts. In live mode, keep the confirmation prompt during interactive use. Reserve --yes for reviewed automation or an already-reviewed replacement plan.

🚀Related Commands

Commands commonly used together with this command.

Initialize Reflow

Create project-owned configuration safely.

Convert Local Tags

Understand local-only replacement behavior.

Examples

Compare local, remote, recovery, and Docker previews.