CP-Utils

Appearance

Getting started ​

In this tutorial we expect you to have:

  • a valid git repository checkout on your local device
  • at least one package.json in the root of your repo (can be a monorepo root)

TIP

Read Setup a demo repository to just test it out

Installation ​

Start by adding the the gitversion package to your root workspace:

sh
$ yarn add -D @cp-utils/gitversion
sh
$ npm add -D @cp-utils/gitversion
sh
$ pnpm add -D @cp-utils/gitversion

First commit ​

Make your first conventional commit which will be used in the rest of this document

sh
# The above command should have modified this file. Lets add it to git
$ git add package.json

# For this demo we will use "feat: ". A better conventional commit tag would be "chore: "
$ git commit -m 'feat: Added gitversion'

TIP

see conventional commits 🔗 for more details

Common cli commands ​

Bump ​

sh
$ yarn gitversion bump
sh
$ npx gitversion bump
sh
$ pnpm gitversion bump

INFO

At this moment we operate in 0.x.x version mode. See 0.x.x releases for more details.

Bump will do the following:

  • restore all versions from the current state in git
  • update all versions in manifest files according to the detected bump type
  • update CHANGELOG.md files according to commit messages
  • generate a bump manifest file in the gitversion.out folder which will be used by the pack command

Pack ​

sh
$ yarn gitversion pack
sh
$ npx gitversion pack
sh
$ pnpm gitversion pack

The pack command will generate packages but will not publish them. The packages are generated by the detected package manager. The output of the pack action will be stored inside the gitversion.out action together with a pack manifest.

The gitversion.out folder can now be stored now in a pipeline artifact so a different stage can publish the results.

TIP

If you do not need to execute anything between bump and pack you can skip the bump command. Pack will execute it when there is no bump manifest.

Publish ​

sh
$ yarn gitversion publish
sh
$ npx gitversion publish
sh
$ pnpm gitversion publish

Publish is the only command that will make permanent changes. Publish will need the workspace in order to update changelog files but will only get its information from the pack information in the gitversion.out folder.

Publish will execute the following:

  • use the package manager to publish the packages
  • add appropriate git tags and push
  • re-apply the changelog entry to the current repository
  • commit the changelogs
  • push the changelogs

TIP

If you do not need to split the pack and publish stages you can skip pack. Publish will try to pack the workspace when there is no pack output in the gitversion.out folder. This means you can use publish as a single command to do bump -> pack -> publish

Reset ​

sh
$ yarn gitversion reset
sh
$ npx gitversion reset
sh
$ pnpm gitversion reset

Reset is not really needed but can be used to just restore youre working space back to "normal". It will:

  • put all versions in manifest files to 0.0.0
  • reset all changes to changelogs back to the repository state

TIP

Add gitversion reset to your pre-commit hook to keep your repository clean from unnecessary changes

Restore ​

sh
$ yarn gitversion restore
sh
$ npx gitversion restore
sh
$ pnpm gitversion restore

Restore is not really needed and internally always used by Bump. Restore will only do the following:

  • read current tags in your git repository and put them into the manifest files

You can use this to see the current state/version of each package.