Metadata-Version: 2.4
Name: distlift
Version: 0.1.3
Summary: A release orchestrator for Python and JavaScript packages
Author-email: Nicu Tofan <nicu.tofan@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ci,git,monorepo,release,versioning
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Version Control
Requires-Python: >=3.11
Requires-Dist: attrs>=23.2
Requires-Dist: tomlkit>=0.13
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# distlift

**distlift** is a small command-line helper for people who ship software
packages. If your project lives in **Git** and you use a **version number**
(like 1.2.3) that you bump when you release, distlift can automate the boring
steps: update the version in your project files, refresh a changelog from
recent commits, create a Git commit and tag, and optionally push to your
remote or build and publish installable packages.

You run it from a terminal in your project folder. It is aimed at **Python**
and **JavaScript** projects out of the box; advanced users can extend it with
plugins.

## What you need first

- **Python 3.11 or newer** installed on your computer.
- Your code in a **Git** repository (distlift talks to Git for tags and
  history).
- A habit of running terminal commands from the folder that contains your
  project (the “repo root”).

## Install

Open a terminal and run:

```text
pip install distlift
```

If you use `pip` only for your user account, that is fine. After install, you
should be able to run:

```text
distlift --help
```

If that prints help text, the tool is on your path. You can also run it as
`python -m distlift` if your Python environment prefers that style.

## The simplest workflow

From your project’s root directory, with a clean saved state in Git (no
half-finished edits you are not ready to commit), run:

```text
distlift
```

With **no extra words**, distlift performs a **patch** release: it bumps the
last part of the version (e.g. 1.0.**4** → 1.0.**5**), updates your manifest
(such as `pyproject.toml` or `package.json`), can update `CHANGELOG.md` when
that is enabled, then commits, tags, and pushes according to your settings.

You can pass **one** of these on the same command instead: `--major`,
`--minor`, `--patch`, or `--version` / `-v` with an exact version (for example
`distlift --minor` or `distlift --version 2.0.0`). You cannot combine two of
them on one run.

**Practice run (nothing is written to Git):**

```text
distlift --dry-run
```

That only shows what *would* happen—safe when you are learning.

**Skip the changelog for one run:**

```text
distlift --no-changelog
```

**Keep the changelog but do not open an editor to tweak the new entry:**

```text
distlift --no-changelog-editor
```

**After a successful release, build installable files locally:**

```text
distlift --build
```

**Build and upload to a registry** (only when you have publish credentials and
configuration set up):

```text
distlift --publish
```

**More detail in the log:**

```text
distlift -V
```

or

```text
distlift --verbose
```

**Work on another folder without `cd` there:**

```text
distlift --repo-root "C:\path\to\your\repo"
```

(Use the path style your operating system expects.)

## Choosing how big the version jump is

The bare `distlift` shortcut (see above) accepts `--major`, `--minor`,
`--patch`, or `--version` / `-v` the same way as `distlift release simple`.

When you prefer the explicit subcommand, use:

```text
distlift release simple --patch
distlift release simple --minor
distlift release simple --major
distlift release simple --version 2.0.0
```

You must pick **exactly one** of those version options for `release simple`.
Add `--dry-run` anytime to rehearse.

## Monorepos (several packages in one repository)

If your repository is configured for **multiple packages**, each with its own
version and tag, use:

```text
distlift release monorepo --all-changed
```

or release specific names:

```text
distlift release monorepo --package my-lib --package my-app
```

You can pass **`--major`**, **`--minor`**, **`--patch`**, or **`--version` /
`-v`** on `release monorepo` as well (at most one per run). If you pass none
of these, **`--default-bump`** controls the bump kind (it defaults to `patch`).

**Unified version:** `--version 2.0.0` sets that **same** next version on
**every package included in that release** (still respecting each package’s
version format). On an interactive terminal, distlift asks you to confirm
before continuing. In non-interactive environments (typical CI), no prompt is
shown.

Add `--dry-run` to preview what would happen without writing to Git.

distlift can maintain a **Keep a Changelog**-style `CHANGELOG.md` using your
Git history (and conventional commit messages when enabled).

**See what would be added for a version, without saving:**

```text
distlift changelog preview --version 1.2.3
```

**Write or update the changelog file for that version:**

```text
distlift changelog update --version 1.2.3
```

By default this may open your text editor so you can polish the entry; add
`--no-editor` to skip that step.

**Create a starter changelog file if you do not have one:**

```text
distlift changelog init
```

In monorepo setups, many changelog commands accept `--package <name>` so the
right subfolder is used.

## Configuration commands

**Show the settings distlift is actually using** (and where each value came
from):

```text
distlift config show
```

**Check that configuration is valid:**

```text
distlift config validate
```

**Create or open config files** for your user account or the whole machine
(these create starter files or open them in your editor):

```text
distlift config init-user
distlift config edit-user
distlift config init-system
distlift config edit-system
```

System-level files on Windows often live under shared “Program Data” folders
and may need administrator rights to edit.

### Choosing the text editor

Whenever distlift needs to open a file in an editor (when polishing a
generated changelog entry, or when you run `distlift config edit-user` or
`distlift config edit-system`), it looks for a command to launch in this
order:

1. The `GIT_EDITOR` environment variable (the same one Git itself uses for
   commit messages).
2. The `VISUAL` environment variable (the POSIX convention for a
   full-screen editor such as `vim`, `nano`, or `code --wait`).
3. The `EDITOR` environment variable (the older POSIX fallback,
   e.g. `notepad` on Windows).
4. The `editor` setting from your **distlift config** file, or the
   `DISTLIFT_EDITOR` environment variable.

So if none of the standard editor environment variables are set on your
system, you can still tell distlift which editor to use by writing one
line in your user config:

```toml
editor = "code --wait"
```

You can place that in any distlift TOML layer
(`distlift.toml` / `.distlift.toml`, `[tool.distlift]` inside
`pyproject.toml`, your user config file, or the system one). The values
saved by `distlift config init-user` already include a commented-out
example.

`distlift config show` prints the effective editor (or `(unset)` when no
layer provides one).

## Plugins

**List extensions distlift loaded** (built-ins and any you configured):

```text
distlift plugins list
```

## Getting unstuck

Every command accepts `--help`, for example:

```text
distlift changelog --help
distlift release simple --help
```

That lists all flags for that command. If something fails, read the message
in the terminal—distlift usually explains whether the problem is
configuration, Git state, or a missing file.

---

*distlift is release automation for developers; it performs real Git
operations when not in `--dry-run`. Always commit or stash unrelated work,
read `--help` before unfamiliar flags, and use `--dry-run` until you are
comfortable with the plan.*
