@henriquehbr/tagit/README.md

A git tag bumper that strictly follows semver

# tagit

> A git tag bumper that strictly follows semver

## Summary

- [Installation](#installation)
- [Usage](#usage)
- [Using `tagit` through Docker](#using-codetagitcode-through-docker)
  - [Using callback scripts](#using-callback-scripts)
  - [Customizing Docker image](#customizing-docker-image)

## Installation

You can use your package manager of choice (npm, yarn or pnpm), but in this
example i'll be using pnpm:

```
pnpm i -g @henriquehbr/tagit
```

## Usage

```
Usage: tagit [options] <version>
A git tag bumper that strictly follows semver

Options:
-p <alpha|beta|rc|stable>
        Create a pre-release using any of the valid identifiers
        (note: "stable" is used when leaving from pre-release versions to a official release)
-f, --force-version <version>
        Use the specified version on the release
-v, --version
        Displays the current version of tagit
-h
        Displays help about using this command
```

## Using `tagit` through Docker

In order to make a release on your project, run:

```
docker run \
    --rm \
    -t \
    -v $(PWD):/repo \
    -e GIT_NAME="$(git config user.name)" \
	-e GIT_EMAIL="$(git config user.email)" \
    henriquehbr/tagit:latest
```

> Your Git name and email are required in order to make the release commit

### Passing arguments to `tagit`

When using this method, the positional parameters passed at the end of the
`docker run` command will be received by the release script inside the
container, in order to pass parameters directly to the `tagit` CLI, you must
assign them to the `TAGIT_FLAGS` environment variable, like on the example
below:

```
docker run \
    --rm \
    -t \
    -v $(PWD):/repo \
    -e GIT_NAME="$(git config user.name)" \
	-e GIT_EMAIL="$(git config user.email)" \
    -e TAGIT_FLAGS="-p beta" \
    henriquehbr/tagit:latest
```

The command above simply instructs tagit to use `beta` as it's pre-release
identifier

### Using callback scripts

If your project requires an extra action before the release, for example,
bumping the version on a `version.txt` file, you can create a callback script
for that, example below:

```sh
#!/bin/sh

version=$1

echo "$version" > version.txt
```

> The new version is passed as the first parameter to the script (`$1`)

After that, remember to mark the callback script as executable, and specify it
as a parameter when running the `tagit` container:

```
docker run \
    --rm \
    -t \
    -v $(PWD):/repo \
    -e GIT_NAME="$(git config user.name)" \
    -e GIT_EMAIL="$(git config user.email)" \
    henriquehbr/tagit:latest \
    ./before-release
```

> If the callback script is not available on your repository like on the example
> above, you can make it available through Docker mounted volumes

### Customizing Docker image

By default, the `henriquehbr/tagit` Docker image available on Docker Hub only
comes with a bare minimum set of tools required to make a release, those being:

- `nodejs` - to run `tagit`
- `git` - to make the release commits
- `git-cliff` - to generate changelogs

That means if you need anything else like `npm` for bumping the `version` field
of `package.json` on your callback release script (assuming you're working on a
Node.js project, for example) you'll need to extend the Docker image to include
the packages and binaries for your specific use case

The example below shows a `Dockerfile` that extends `henriquehbr/tagit` and
installs `npm` over it:

```dockerfile
FROM henriquehbr/tagit:latest

USER root

RUN apk add --no-cache npm

USER tagit
```

> Remember that it's **strongly recommended** to switch back to the `tagit` user
> after performing operations that requires superuser permissions

And build it with the command below:

```
docker build --build-arg HOST_USER_UID=$(id -u) -t release .
```

> The host user id is required to give permission to the container user over the
> repository files

Customized containers can be launched using the exact same
[parameters](#using-codetagitcode-through-docker) of the default
`henriquehbr/tagit` container