Metadata-Version: 2.4
Name: gitflow_manager
Version: 3.0.0
Summary: This package contains the Anacision Git Manager.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: gitpython>=3.1.24
Requires-Dist: pystache>=0.6.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: requests>=2.27.1
Requires-Dist: tomlkit>=0.13.3
Provides-Extra: dev
Requires-Dist: pre-commit>=4.0.1; extra == "dev"
Requires-Dist: ruff==0.6.9; extra == "dev"
Requires-Dist: setuptools>=75.3.0; extra == "dev"
Requires-Dist: twine>=6.0.1; extra == "dev"

# Anacision Gitflow Manager

## Description

The gitflow manager is a tool that helps maintaining clean versioning and documentation in code projects.
By using the gitflow manager one can make sure to stick to the
[GitFlow](https://nvie.com/posts/a-successful-git-branching-model) rules. Furthermore, it helps maintain a good
changelog and documentation.
Whenever you want to start a new branch or merging it back to dev/main run the `gfm` command.
It uses a dialog to define the type of new branch (feature, bugfix, hotfix, release) or merge option as well as setting
the required changelog messages.
It then automatically updates version numbers, checks out corresponding branches and commits/merges according to the
GitFlow.
Changes are also pushed to the Git Host via ssh or https and for protected branches merge requests are initialized.
Currently, the gitflow manager supports Gitlab and Bitbucket as hosting platforms.

### Versioning

- Utilize the gitflow manager in projects to make sure that you easily stick to these rules:
  - Versions are defined in the format *Major.Minor.Hotfix*. New versions are created when opening the hotfix or release
  branch.
  - The hotfix branch is only allowed to be started from main branch, to increase the Hotfix version digit only and to
  be merged into main (+ dev thereafter).
  - The release branch is only allowed to be started from dev, to increase the minor or major version digit and to be
  merged into main (+ dev thereafter). In case of a new major version, the minor and hotfix digit is reset to 0. In case
  of a new minor version, the hotfix digit is reset to 0.
  - The bugfix and feature branches are only allowed to be started from dev, increase no version number and are merged
  back to dev.
  - All new branches need a description in the change log, which has separate "Added", "Changed" and "Fixed" sections.

### Supported branches with gitflow manager

- **main**: Permanent, stable, (normally) protected branch used for deployment. Each commit has a new version. Merge
requests only come from release or hotfix branch.
- **dev**: Permanent development branch. Gets merge requests from feature, hotfix and release branch.
- **release/vX.X.X**: Release branch. Branched off from dev branch with new minor or major version. When the branch is
finished, it is merged into main and dev branch. Intermediate merges into dev are allowed, too. Merges from dev into
release branch are not allowed.
- **feature/xxxxxx**: For features to be developed. Branched off from dev branch and will be merged back into dev after
finishing feature.
- **bugfix/xxxxxx**: For bugs to be fixed. Branched off from dev branch and will be merged back into dev after
finishing the fix.
- **hotfix/vX.X.X**: Hotfix branch for fixes from deployed code. Branched off from main branch with new hotfix
version. When done, is merged into main and dev branch.

### Tagging

- Currently, tagging is not done automatically. You can configure yourself a CI pipeline, that does the job for you.

## Getting started

### Installation

For a global CLI installation with uv, use:

```bash
uv tool install gitflow-manager
```

Alternatively, install it with pip:

```bash
pip install gitflow-manager
```

Restart the terminal if the `gfm` command is not available immediately after installation.

For local development from this repository, install the checkout in editable mode:

```bash
python -m pip install -e .
```

### Usage

- When using the first time, run `gfm --init` in the root of the project.
- During init, `gfm` detects common version setups automatically (`VERSION`, dynamic pyproject versioning, `src`/flat
  Python packages). Press Enter to accept the detected setup or type `edit` to override it.
- Subsequently, just type `gfm` each time you need to branch or merge (or add change log information), and follow the
dialog
- To regenerate the rendered changelog without starting a branch flow, run `gfm regenerate`.

### Changelog test

The generic changelog integration test is in [`tests/integrationstest/GFM_CHANGELOG_TESTS.md`](tests/integrationstest/GFM_CHANGELOG_TESTS.md).
Create a separate Git test project first, run `gfm --init` so that it contains
`.gitflow_manager.yml`, then adjust the two variables in the test instructions.

### Version file projects

Projects that do not use Python packaging can store their version in a plain version file. Create a file such as
`VERSION` with only the semantic version in it:

```text
1.2.3
```

During `gfm --init`, enter `VERSION` when asked for a version file path. Or add it manually:

```yaml
version_file: VERSION
```

When this option is set, `gfm` reads and updates that file instead of requiring `pyproject.toml` or a Python
`__init__.py`.

### Changelog fragments

`gfm` stores branch changelog entries under `docs/source/change_log.d/` and automatically includes them in the next
release or hotfix changelog.

### Monorepo projects

`gfm` can manage additional app versions in monorepos. Enable this during `gfm --init` or add it to
`.gitflow_manager.yml`:

```yaml
monorepo: true
monorepo_apps:
  - src/app_a
  - src/app_b
```

If `monorepo_apps` is empty, `gfm` auto-detects one-level apps under the configured project layout, for example
`src/*/__init__.py`. Each app must expose a `__version__ = "X.Y.Z"` value. `__app_name__` is optional and used only for
display.

On release branches, `gfm` increases the versions of apps that changed since branching off from `main`. On hotfix
branches, it asks which apps are affected.
