npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

gitex-flow

v2.4.1

Published

A git flow extension that provides some additional automation and feature improvements. The aim of the project is to offer a complete process chain in order to organize the releases of your projects as easily as possible.

Downloads

958

Readme

logo-banner

gitex-flow is a git flow extension that adds some automation and features to the standardized process. It also represents a tool chain for a continuous release strategy that automates as many work steps as possible.

:interrobang: If you are using visual studio code you can simply use the official vscode extension of gitex-flow.

Table of content

Introduction

In my experience as a software developer, one of the most important parts of a software project is a precisely defined and largely automated release and deployment process. Modern software projects often involve multiple autonomous projects (e.g. microservices), each with their own release cycles. Git flow offers a standardized release strategy that helps you get this problem under control.

In addition, using git flow covers some common requirements and allows other project management issues to be automated:

  1. Easy creation of frequent releases: Continous and frequent releases are mostly an essential part of the project requirement, especially for agile projects. A deployment can be very error prune and time intense. For this reason, it is worth investing in a deployment process that is as simple as possible.

  2. Simplifies the automation of build tasks: The standardization of releases allows easier automation of versioning (e.g. semantic versioning) and build tasks (e.g. building npm packages or executables).

  3. Good scaling for different team sizes: When a project gets bigger, more complicated or several developers are working on it, a defined release process becomes more and more important.

  4. Keep the user informed about changes and features: Frequent releases makes it harder for users to track the new versions and their changes. Transparency is important in increasing the acceptance of the software and allows to participate the user into the software project.

Features

gitex-flow is fully compatible with git flow. This means that gitex-flow uses the same commands as git flow, but with additional functionality:

  1. Automatic calculation of versions for (pre-)release and hotfix branches using semantic versioning (SemVer) and BREAKING CHANGE flag of conventional commits.
  2. Automatic dumping of npm project versions (package.json, package-lock.json).
  3. Automatic creation of a changelog for each version by conventional commits.

User documentation

gitex-flow can be used as a npm package in your node.js project. You can install them either as global or project reference.

Prerequisite

NOTICE:

The project git-flow (AVH edition) has been archived on Jun 19, 2023 and is no longer supported. However, there is a follow-on project git-flow (CJS edition) which is actively being developed and is 100% backward compatible.

Installation

As a global reference

#> npm install -g gitex-flow

As a project dependency

You can also install gitex-flow as a npm development dependency in your project:

#> npm install --save-dev gitex-flow

To integrate the gitex workflow into your project, add the following lines to the scripts section of your package.json:

"scripts": {
    ...
    "init": "gitex-flow init",
    "feature:start": "gitex-flow feature start",
    "feature:finish": "gitex-flow feature finish",
    "release:start": "gitex-flow release start",
    "release:finish": "gitex-flow release finish",
    "hotfix:start": "gitex-flow hotfix start",
    "hotfix:finish": "gitex-flow hotfix finish",
    "bugfix:start": "gitex-flow bugfix start",
    "bugfix:finish": "gitex-flow bugfix finish",
    "support:start": "gitex-flow support start",
    "support:finish": "gitex-flow support finish"
    "prerelease:alpha": "gitex-flow prerelease alpha start",
    "prerelease:beta": "gitex-flow prerelease beta start"
    ...
}

Initialization

Once after the installation or after cloning a new local repository you have to initialize it by executing the following command:

#> gitex-flow init

or if it was installed as a project dependency

#> npm run init

For reasons of simplicity, I only use the global installation for the following documentation examples.

Configuation

To configure gitex-flow you can create a configuration file .gitex[[-flow][.json]]. The following JSON shows the schema and the default values of the configuration:

{
  "gitFlowConfig": {
    "masterBranch": "master",
    "developBranch": "develop",
    "featureBranchPrefix": "feature/",
    "bugfixBranchPrefix": "bugfix/",
    "releaseBranchPrefix": "release/",
    "hotfixBranchPrefix": "hotfix/",
    "supportBranchPrefix": "support/",
    "versionTagPrefix": null
  },
  "projectConfig": {
    "projectPath": "./",
    "autoStash": true,
    "changelogFileName": "CHANGELOG.md",       // @deprecated
    "storeLatestChangelog": false,             // @deprecated
    "conventionalChangelogPresent": "angular", // @deprecated
    "changelog": {
      "type": "ConventionalChangelog",
      "changelogFileName": "CHANGELOG.md",
      "storeLatestChangelog": false,
      "conventionalChangelogPresent": "angular"
    },
    "conventionalCommit": {
      "referenceActions": [
        "close",
        "closes",
        "closed",
        "fix",
        "fixes",
        "fixed",
        "resolve",
        "resolves",
        "resolved",
        "refs",
        "references",
      ],
      "noteKeywords": ["BREAKING CHANGE", "SECURITY", "REMOVED"],
      // *for all options visit documentation of conventional-commits-parser
    },
    "versionFile": "package.json",
    "bumpVersionFiles": [
      "package.json",
      "package-lock.json"
    ]
  },
  "log4jsConfig": {
    "appenders": { "console": { "type": "console" } },
    "categories": { "default": { "appenders": ["console"], "level": "info" } }
  },
}

Further information on the available configurations can be found in the API documentation.

For all options of the conventionalCommit block visit the project of the underlying conventional-commits-parser.

To show the loaded git flow configuration you can execute the command:

#> gitex-flow config

Conventional commits guideline

To use gitex flow properly, you have to follow the conventional commits guideline.

An example for a matching conventional angular commit message:

feat(gflow): Implemented automatic naming when creating branches

The name of the release and hotfix branch is set automatically when it is created.

closes #5

or

feat(config): Made gitex-flow configurable

Added configuration data structure and introduced optional config file '.gitex'.

BREAKING CHANGE: Adapted API by adding an options to the affected modules (classes).

closes #10

or

fix(service): Removed support of unencrypted HTTP protocol

This unencrypted protocol has led to several vulnerabilities in the framework.

SECURITY: Only encrypted protocols are now allowed
BREAKING CHANGE: Removed HTTP endpoint in web service.

closes #941, refs #1094, #1100

Changelog generator

Gitex flow provides a modular changelog generator. The framework provides some useful default implementations that you can easily configure in the changelog block of the projectConfig section. All implementations of the changelog generator have the following common options:

  • basePath: the base folder containing the changelog file (default: projectConfig.projectPath otherwise process.cwd())
  • changelogFileName: The name of the changelog (default: CHANGELOG.md)
  • storeLatestChangelog: Keep the changelog of the latest version as a separate file named CHANGELOG.latest.md (default: false)

Depending on the implementation there may be additional properties.

| Type | Description | Options | Note | | ----------------------- | :-------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------- | | None | Deactivates the changelog generator. | - | | | ConventionalChangelog | Implementation of the conventional-changelog generator. | ConventionalChangelogWriterOptions | default | | KeepAChangelog | Implementation of the keep-a-changelog generator. | KeepAChangelogWriterOptions | |

Changelog commands

To interact with the changelog generator, gitex-flow provides some commands.

Print the changelog

The following command prints the complete changelog as Markdown to the console.

#> gitex-flow changelog

Print unreleased changes

The following command prints the unreleased changes to the console.

#> gitex-flow changelog unreleased

Manually updating the changelog

The following command updates the changelog with a given version and name.

#> gitex-flow changelog update [version] [name]

Git flow branches and tags

Git flow offers five branches for different use cases. For some branch types several branches can be active at the same time (features, bugfixes, support-branches). For others (release, hotfix) only one. Furthermore, gitex-flow extends the classic git-flow branches with prerelease tags.

Feature

Features are branches based on the develop branch to add new functionality to the application. Feature branches can exist over many releases and can be updated regularly with the latest changes of the develop branch.

List active features

#> gitex-flow feature

Start feature

I recommend to use the issue reference of the corresponding ticket system as the feature name (ex. #42).

#> gitex-flow feature start <name>

Finish feature

The name does not need to be specified if the feature branch has already been checked out.

#> gitex-flow feature finish [name]

Bugfix

Bugfix branches are similar to feature branches, but intented for bug fixing. This is useful for bugs which are not fixable as a hotfix (breaking change, low prio bug).

List active bugfixes

#> gitex-flow bugfix

Start bugfix

I recommend to use the issue reference of the corresponding ticket system as the bugfix name (ex. #42).

#> gitex-flow bugfix start <name>

Finish bugfix

The name does not need to be specified if the bugfix branch has already been checked out.

#> gitex-flow bugfix finish [name]

Release

Releases are branches that are based on the develop branch, which freezes the current code and marks a feature stop. The code from the release branch can be published to the consolidation (test) system. Only bugfixes are allowed to be commited on the release branch. If the release is stable, the release branch can be finished and merged into the master branch.

List active release

#> gitex-flow release

Start release

When starting a release, gitex-flow automatically updates the versions in package.json and package-lock.json and updates the changelog based on the commits since the last release.

By default, a release is always a minor release. However, in case there has been a BREAKING CHANGE since the last release, it is treated as a major release.

If no custom name is specified for the release, then gitex-flow uses the calculated version as the name.

#> gitex-flow release start [name]

Finish release

The name does not need to be specified if the release branch has already been checked out.

#> gitex-flow release finish [name]

Hotfix

Hotfixes are bug fixes based on a released version.

List active hotfix

#> gitex-flow hotfix

Start hotfix

When starting a hotfix, gitex-flow automatically updates the versions in package.json and package-lock.json.

A hotfix is always a patch. It's not allowed to commit breaking changes or new features on a hotfix branch.

If no custom name is specified for the hotfix, then gitex-flow uses patch version as the name.

#> gitex-flow hotfix start [name]

Finish hotfix

After the bugfixes commited to the hotfix branch the changelog can be updated.

The name does not need to be specified if the release branch has already been checked out.

#> gitex-flow hotfix finish [name]

Support

Support branches are based on a released version to provide long term support of a program version.

List active support

#> gitex-flow support

Start support

By default, the base of a new support branch is the master branch.

#> gitex-flow support start <name> [base]

Finish support

:interrobang: Some git flow implementations do not support finishing support branches.

The name does not need to be specified if the release branch has already been checked out.

#> gitex-flow support finish [name]

Prerelease

There are two types of pre-releases: alpha and beta releases.

  1. An alpha release is an early version of a software during the initial development phase, often unstable and tested internally by developers. Gitex-flow enables the creation of alpha releases from the develop or a feature branch.

  2. A beta release is the phase following alpha, where the software has fewer bugs and is more stable. It's tested by a limited number of external users, known as beta testers, to gather feedback before the final release. Gitex-flow enables the creation of beta releases from the release or the hotfix branch.

List pre-released versions

#> gitex-flow prerelease <alpha|beta>

Create a pre-release

By default, the base of a new prerelease is the current branch. However, a branch can also be specified explicitly, e.g. develop or hotfix/1.0.2. If a prerelease is executed on a inappropriate branch, an error occurs.

#> gitex-flow prerelease <alpha|beta> start [base]

Developer documentation (API)

If you like to use gitex-flow in your code, you can use the typescript API.

gitex-flow is implemented as a wrapper of an arbitary git flow implementation.

import { AvhGitFlow, GFlow, GFlowConfig } from 'gitex-flow';

// Options with default values
const gFlowConfig: GFlowConfig = {
  gitFlowConfig: {
    masterBranch: 'master',
    developBranch: 'develop',
    featureBranchPrefix: 'feature/',
    bugfixBranchPrefix: 'bugfix/',
    releaseBranchPrefix: 'release/',
    hotfixBranchPrefix: 'hotfix/',
    supportBranchPrefix: 'support/',
    versionTagPrefix: undefined,
  },
  projectConfig: {
    projectPath: './',
    autoStash: true,
    changelogFileName: 'CHANGELOG.md', // @deprecated
    storeLatestChangelog: false, // @deprecated
    conventionalChangelogPresent: 'angular', // @deprecated
    changelog: {
      type: 'ConventionalChangelog',
      changelogFileName: 'CHANGELOG.md',
      storeLatestChangelog: false,
      conventionalChangelogPresent: 'angular',
    },
    conventionalCommit: {
      referenceActions: [
        'close',
        'closes',
        'closed',
        'fix',
        'fixes',
        'fixed',
        'resolve',
        'resolves',
        'resolved',
        'refs',
        'references',
      ],
      noteKeywords: ['BREAKING CHANGE', 'SECURITY', 'REMOVED'],
    },
    versionFile: 'package.json',
    bumpVersionFiles: ['package.json', 'package-lock.json'],
  },
  log4jsConfig: {
    appenders: { console: { type: 'console' } },
    categories: { default: { appenders: ['console'], level: 'info' } },
  },
};

const gitFlow = new AvhGitFlow();
const gFlow = new GFlow(gitFlow, gFlowConfig);
// ...

The full API documentation can be found here.

Troubleshooting

  1. Executing the gitex-flow [...] command results in the following error:

    Branches '<branch>' and 'origin/<branch>' have diverged.

    Fatal: And branch '<branch>' may be fast-forwarded

    Reason: The executed command affects a branch where the local and remote state of the git repository have diverged.

    Problem: This problem cannot be solved automatically, because the solution depends heavily on the state of the local git repository.

    Solution: Make sure that the affected local branch is up to date. In most cases this is easy (e.t. git pull --rebase), but there are also cases where a manual merge is necessary.