{"id":30288304,"url":"https://github.com/gitex-flow/gitex-flow-node","last_synced_at":"2025-08-16T22:04:13.062Z","repository":{"id":42116301,"uuid":"260453870","full_name":"gitex-flow/gitex-flow-node","owner":"gitex-flow","description":"A git flow extension that provides some additional automation and feature improvements. The goal of the project is to offer a complete process chain in order to organize the releases of your projects as easily as possible.","archived":false,"fork":false,"pushed_at":"2025-02-18T03:49:53.000Z","size":804,"stargazers_count":17,"open_issues_count":5,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-08-05T01:23:30.484Z","etag":null,"topics":["conventional-commits","frequent-releases","git","git-flow","gitex-flow","release","semantic","semantic-versioning","semver","workflow"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gitex-flow.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.latest.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-01T12:27:57.000Z","updated_at":"2024-08-23T21:29:22.000Z","dependencies_parsed_at":"2024-06-21T07:12:54.638Z","dependency_job_id":"c0464c6b-ddd5-49d1-b05c-96103e0b67d1","html_url":"https://github.com/gitex-flow/gitex-flow-node","commit_stats":{"total_commits":187,"total_committers":4,"mean_commits":46.75,"dds":"0.15508021390374327","last_synced_commit":"629150d5ee01c6716c0129d17610b7a583f98713"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/gitex-flow/gitex-flow-node","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitex-flow%2Fgitex-flow-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitex-flow%2Fgitex-flow-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitex-flow%2Fgitex-flow-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitex-flow%2Fgitex-flow-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gitex-flow","download_url":"https://codeload.github.com/gitex-flow/gitex-flow-node/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitex-flow%2Fgitex-flow-node/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269713883,"owners_count":24463244,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["conventional-commits","frequent-releases","git","git-flow","gitex-flow","release","semantic","semantic-versioning","semver","workflow"],"created_at":"2025-08-16T22:03:12.638Z","updated_at":"2025-08-16T22:04:13.044Z","avatar_url":"https://github.com/gitex-flow.png","language":"TypeScript","readme":"![logo-banner](./assets/gitex-flow-logo-banner.svg)\n\n**gitex-flow** is a [git flow](https://nvie.com/posts/a-successful-git-branching-model/) extension that adds some automation and features to the standardized process.\nIt also represents a tool chain for a continuous release strategy that automates as many work steps as possible.\n\n\u003e :interrobang:\n\u003e If you are using [visual studio code](https://code.visualstudio.com/) you can simply use the official [vscode extension](https://marketplace.visualstudio.com/items?itemName=gitex-flow.gitex-flow-vscode) of gitex-flow.\n\n# Table of content\n\n- [Table of content](#table-of-content)\n- [Introduction](#introduction)\n- [Features](#features)\n- [User documentation](#user-documentation)\n  - [Prerequisite](#prerequisite)\n  - [Installation](#installation)\n    - [As a global reference](#as-a-global-reference)\n    - [As a project dependency](#as-a-project-dependency)\n  - [Initialization](#initialization)\n  - [Configuation](#configuation)\n  - [Conventional commits guideline](#conventional-commits-guideline)\n  - [Changelog generator](#changelog-generator)\n    - [Changelog commands](#changelog-commands)\n  - [Git flow branches and tags](#git-flow-branches-and-tags)\n    - [Feature](#feature)\n    - [Bugfix](#bugfix)\n    - [Release](#release)\n    - [Hotfix](#hotfix)\n    - [Support](#support)\n    - [Prerelease](#prerelease)\n- [Developer documentation (API)](#developer-documentation-api)\n- [Troubleshooting](#troubleshooting)\n\n# Introduction\n\nIn 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.\nModern software projects often involve multiple autonomous projects (e.g. microservices), each with their own release cycles.\nGit flow offers a standardized release strategy that helps you get this problem under control.\n\nIn addition, using git flow covers some common requirements and allows other project management issues to be automated:\n\n1. **Easy creation of frequent releases**:\n   Continous and frequent releases are mostly an essential part of the project requirement, especially for agile projects.\n   A deployment can be very error prune and time intense.\n   For this reason, it is worth investing in a deployment process that is as simple as possible.\n\n2. **Simplifies the automation of build tasks**:\n   The standardization of releases allows easier automation of versioning (e.g. semantic versioning) and build tasks (e.g. building npm packages or executables).\n\n3. **Good scaling for different team sizes**:\n   When a project gets bigger, more complicated or several developers are working on it, a defined release process becomes more and more important.\n\n4. **Keep the user informed about changes and features**:\n   Frequent releases makes it harder for users to track the new versions and their changes.\n   Transparency is important in increasing the acceptance of the software and allows to participate the user into the software project.\n\n# Features\n\n**gitex-flow** is fully compatible with **git flow**.\nThis means that gitex-flow uses the same commands as git flow, but with additional functionality:\n\n1. Automatic calculation of versions for (pre-)release and hotfix branches using [semantic versioning (SemVer)](https://semver.org/) and BREAKING CHANGE flag of [conventional commits](#conventional-commits-guideline).\n2. Automatic dumping of npm project versions (`package.json`, `package-lock.json`).\n3. Automatic creation of a changelog for each version by [conventional commits](#conventional-commits-guideline).\n\n# User documentation\n\n**gitex-flow** can be used as a npm package in your **node.js** project.\nYou can install them either as global or project reference.\n\n## Prerequisite\n\n- [git](https://git-scm.com/downloads) is installed\n- [git-flow (AVH edition)](https://github.com/petervanderdoes/gitflow-avh) is installed\n- [node.js](https://nodejs.org/en/) is installed\n\n\u003e **NOTICE:**\n\u003e\n\u003e The project [git-flow (AVH edition)](https://github.com/petervanderdoes/gitflow-avh) has been archived on Jun 19, 2023 and is no longer supported.\n\u003e However, there is a follow-on project [git-flow (CJS edition)](https://github.com/CJ-Systems/gitflow-cjs) which is actively being developed and is 100% backward compatible.\n\n## Installation\n\n### As a global reference\n\n```\n#\u003e npm install -g gitex-flow\n```\n\n### As a project dependency\n\nYou can also install gitex-flow as a npm development dependency in your project:\n\n```\n#\u003e npm install --save-dev gitex-flow\n```\n\nTo integrate the gitex workflow into your project, add the following lines to the `scripts` section of your `package.json`:\n\n```javascript\n\"scripts\": {\n    ...\n    \"init\": \"gitex-flow init\",\n    \"feature:start\": \"gitex-flow feature start\",\n    \"feature:finish\": \"gitex-flow feature finish\",\n    \"release:start\": \"gitex-flow release start\",\n    \"release:finish\": \"gitex-flow release finish\",\n    \"hotfix:start\": \"gitex-flow hotfix start\",\n    \"hotfix:finish\": \"gitex-flow hotfix finish\",\n    \"bugfix:start\": \"gitex-flow bugfix start\",\n    \"bugfix:finish\": \"gitex-flow bugfix finish\",\n    \"support:start\": \"gitex-flow support start\",\n    \"support:finish\": \"gitex-flow support finish\"\n    \"prerelease:alpha\": \"gitex-flow prerelease alpha start\",\n    \"prerelease:beta\": \"gitex-flow prerelease beta start\"\n    ...\n}\n```\n\n## Initialization\n\nOnce after the installation or after cloning a new local repository you have to initialize it by executing the following command:\n\n```\n#\u003e gitex-flow init\n```\n\nor if it was installed as a project dependency\n\n```\n#\u003e npm run init\n```\n\n\u003e For reasons of simplicity, I only use the global installation for the following documentation examples.\n\n## Configuation\n\nTo configure **gitex-flow** you can create a configuration file `.gitex[[-flow][.json]]`.\nThe following JSON shows the schema and the default values of the configuration:\n\n```javascript\n{\n  \"gitFlowConfig\": {\n    \"masterBranch\": \"master\",\n    \"developBranch\": \"develop\",\n    \"featureBranchPrefix\": \"feature/\",\n    \"bugfixBranchPrefix\": \"bugfix/\",\n    \"releaseBranchPrefix\": \"release/\",\n    \"hotfixBranchPrefix\": \"hotfix/\",\n    \"supportBranchPrefix\": \"support/\",\n    \"versionTagPrefix\": null\n  },\n  \"projectConfig\": {\n    \"projectPath\": \"./\",\n    \"autoStash\": true,\n    \"changelogFileName\": \"CHANGELOG.md\",       // @deprecated\n    \"storeLatestChangelog\": false,             // @deprecated\n    \"conventionalChangelogPresent\": \"angular\", // @deprecated\n    \"changelog\": {\n      \"type\": \"ConventionalChangelog\",\n      \"changelogFileName\": \"CHANGELOG.md\",\n      \"storeLatestChangelog\": false,\n      \"conventionalChangelogPresent\": \"angular\"\n    },\n    \"conventionalCommit\": {\n      \"referenceActions\": [\n        \"close\",\n        \"closes\",\n        \"closed\",\n        \"fix\",\n        \"fixes\",\n        \"fixed\",\n        \"resolve\",\n        \"resolves\",\n        \"resolved\",\n        \"refs\",\n        \"references\",\n      ],\n      \"noteKeywords\": [\"BREAKING CHANGE\", \"SECURITY\", \"REMOVED\"],\n      // *for all options visit documentation of conventional-commits-parser\n    },\n    \"versionFile\": \"package.json\",\n    \"bumpVersionFiles\": [\n      \"package.json\",\n      \"package-lock.json\"\n    ]\n  },\n  \"log4jsConfig\": {\n    \"appenders\": { \"console\": { \"type\": \"console\" } },\n    \"categories\": { \"default\": { \"appenders\": [\"console\"], \"level\": \"info\" } }\n  },\n}\n\n```\n\nFurther information on the [available configurations](https://gitex-flow.github.io/gitex-flow-node/interfaces/configs_GFlowConfig.GFlowConfig.html) can be found in the API documentation.\n\nFor all options of the `conventionalCommit` block visit the project of the underlying [conventional-commits-parser](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser#options).\n\nTo show the loaded git flow configuration you can execute the command:\n\n```shell\n#\u003e gitex-flow config\n```\n\n## Conventional commits guideline\n\nTo use gitex flow properly, you have to follow the [conventional commits guideline](https://www.conventionalcommits.org/en/v1.0.0/).\n\nAn example for a matching conventional angular commit message:\n\n```\nfeat(gflow): Implemented automatic naming when creating branches\n\nThe name of the release and hotfix branch is set automatically when it is created.\n\ncloses #5\n```\n\nor\n\n```\nfeat(config): Made gitex-flow configurable\n\nAdded configuration data structure and introduced optional config file '.gitex'.\n\nBREAKING CHANGE: Adapted API by adding an options to the affected modules (classes).\n\ncloses #10\n```\n\nor\n\n```\nfix(service): Removed support of unencrypted HTTP protocol\n\nThis unencrypted protocol has led to several vulnerabilities in the framework.\n\nSECURITY: Only encrypted protocols are now allowed\nBREAKING CHANGE: Removed HTTP endpoint in web service.\n\ncloses #941, refs #1094, #1100\n```\n\n## Changelog generator\n\nGitex flow provides a modular changelog generator.\nThe framework provides some useful default implementations that you can easily configure in the `changelog` block of the `projectConfig` section.\nAll implementations of the changelog generator have the following common options:\n\n- `basePath`: the base folder containing the changelog file (default: `projectConfig.projectPath` otherwise `process.cwd()`)\n- `changelogFileName`: The name of the changelog (default: `CHANGELOG.md`)\n- `storeLatestChangelog`: Keep the changelog of the latest version as a separate file named `CHANGELOG.latest.md` (default: `false`)\n\nDepending on the implementation there may be additional properties.\n\n| Type                    | Description                                                                                                                 | Options                                                                                                                                                                     | Note      |\n| ----------------------- | :-------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------- |\n| `None`                  | Deactivates the changelog generator.                                                                                        | -                                                                                                                                                                           |           |\n| `ConventionalChangelog` | Implementation of the [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) generator. | [ConventionalChangelogWriterOptions](https://gitex-flow.github.io/gitex-flow-node/interfaces/changelog_ConventionalChangelogWriter.ConventionalChangelogWriterOptions.html) | `default` |\n| `KeepAChangelog`        | Implementation of the [keep-a-changelog](https://keepachangelog.com/en/1.0.0/) generator.                                   | [KeepAChangelogWriterOptions](https://gitex-flow.github.io/gitex-flow-node/interfaces/changelog_KeepAChangelogWriter.KeepAChangelogWriterOptions.html)                      |           |\n\n### Changelog commands\n\nTo interact with the changelog generator, gitex-flow provides some commands.\n\n**Print the changelog**\n\nThe following command prints the complete changelog as Markdown to the console.\n\n```shell\n#\u003e gitex-flow changelog\n```\n\n**Print unreleased changes**\n\nThe following command prints the unreleased changes to the console.\n\n```shell\n#\u003e gitex-flow changelog unreleased\n```\n\n**Manually updating the changelog**\n\nThe following command updates the changelog with a given version and name.\n\n```shell\n#\u003e gitex-flow changelog update [version] [name]\n```\n\n## Git flow branches and tags\n\nGit flow offers five branches for different use cases.\nFor some branch types several branches can be active at the same time (_features_, _bugfixes_, _support-branches_). For others (_release_, _hotfix_) only one.\nFurthermore, gitex-flow extends the classic git-flow branches with prerelease tags.\n\n### Feature\n\nFeatures 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.\n\n**List active features**\n\n```shell\n#\u003e gitex-flow feature\n```\n\n**Start feature**\n\nI recommend to use the issue reference of the corresponding ticket system as the feature name (ex. #42).\n\n```shell\n#\u003e gitex-flow feature start \u003cname\u003e\n```\n\n**Finish feature**\n\nThe name does not need to be specified if the feature branch has already been checked out.\n\n```shell\n#\u003e gitex-flow feature finish [name]\n```\n\n### Bugfix\n\nBugfix branches are similar to feature branches, but intented for bug fixing.\nThis is useful for bugs which are not fixable as a hotfix (breaking change, low prio bug).\n\n**List active bugfixes**\n\n```shell\n#\u003e gitex-flow bugfix\n```\n\n**Start bugfix**\n\nI recommend to use the issue reference of the corresponding ticket system as the bugfix name (ex. #42).\n\n```shell\n#\u003e gitex-flow bugfix start \u003cname\u003e\n```\n\n**Finish bugfix**\n\nThe name does not need to be specified if the bugfix branch has already been checked out.\n\n```shell\n#\u003e gitex-flow bugfix finish [name]\n```\n\n### Release\n\nReleases are branches that are based on the develop branch, which freezes the current code and marks a feature stop.\nThe code from the release branch can be published to the consolidation (test) system.\nOnly bugfixes are allowed to be commited on the release branch.\nIf the release is stable, the release branch can be finished and merged into the master branch.\n\n**List active release**\n\n```shell\n#\u003e gitex-flow release\n```\n\n**Start release**\n\nWhen 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.\n\nBy 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.\n\nIf no custom name is specified for the release, then gitex-flow uses the calculated version as the name.\n\n```shell\n#\u003e gitex-flow release start [name]\n```\n\n**Finish release**\n\nThe name does not need to be specified if the release branch has already been checked out.\n\n```shell\n#\u003e gitex-flow release finish [name]\n```\n\n### Hotfix\n\nHotfixes are bug fixes based on a released version.\n\n**List active hotfix**\n\n```shell\n#\u003e gitex-flow hotfix\n```\n\n**Start hotfix**\n\nWhen starting a hotfix, gitex-flow automatically updates the versions in `package.json` and `package-lock.json`.\n\nA hotfix is always a patch.\nIt's not allowed to commit breaking changes or new features on a hotfix branch.\n\nIf no custom name is specified for the hotfix, then gitex-flow uses patch version as the name.\n\n```shell\n#\u003e gitex-flow hotfix start [name]\n```\n\n**Finish hotfix**\n\nAfter the bugfixes commited to the hotfix branch the changelog can be updated.\n\nThe name does not need to be specified if the release branch has already been checked out.\n\n```shell\n#\u003e gitex-flow hotfix finish [name]\n```\n\n### Support\n\nSupport branches are based on a released version to provide long term support of a program version.\n\n**List active support**\n\n```shell\n#\u003e gitex-flow support\n```\n\n**Start support**\n\nBy default, the base of a new support branch is the `master` branch.\n\n```shell\n#\u003e gitex-flow support start \u003cname\u003e [base]\n```\n\n**Finish support**\n\n\u003e :interrobang:\n\u003e Some git flow implementations do not support finishing support branches.\n\nThe name does not need to be specified if the release branch has already been checked out.\n\n```shell\n#\u003e gitex-flow support finish [name]\n```\n\n### Prerelease\n\nThere are two types of pre-releases: `alpha` and `beta` releases.\n\n1. 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.\n\n2. 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.\n\n**List pre-released versions**\n\n```shell\n#\u003e gitex-flow prerelease \u003calpha|beta\u003e\n```\n\n**Create a pre-release**\n\nBy default, the base of a new prerelease is the current branch.\nHowever, a branch can also be specified explicitly, e.g. `develop` or `hotfix/1.0.2`.\nIf a prerelease is executed on a inappropriate branch, an error occurs.\n\n```shell\n#\u003e gitex-flow prerelease \u003calpha|beta\u003e start [base]\n```\n\n# Developer documentation (API)\n\nIf you like to use **gitex-flow** in your code, you can use the typescript API.\n\n**gitex-flow** is implemented as a wrapper of an arbitary **git flow** implementation.\n\n```typescript\nimport { AvhGitFlow, GFlow, GFlowConfig } from 'gitex-flow';\n\n// Options with default values\nconst gFlowConfig: GFlowConfig = {\n  gitFlowConfig: {\n    masterBranch: 'master',\n    developBranch: 'develop',\n    featureBranchPrefix: 'feature/',\n    bugfixBranchPrefix: 'bugfix/',\n    releaseBranchPrefix: 'release/',\n    hotfixBranchPrefix: 'hotfix/',\n    supportBranchPrefix: 'support/',\n    versionTagPrefix: undefined,\n  },\n  projectConfig: {\n    projectPath: './',\n    autoStash: true,\n    changelogFileName: 'CHANGELOG.md', // @deprecated\n    storeLatestChangelog: false, // @deprecated\n    conventionalChangelogPresent: 'angular', // @deprecated\n    changelog: {\n      type: 'ConventionalChangelog',\n      changelogFileName: 'CHANGELOG.md',\n      storeLatestChangelog: false,\n      conventionalChangelogPresent: 'angular',\n    },\n    conventionalCommit: {\n      referenceActions: [\n        'close',\n        'closes',\n        'closed',\n        'fix',\n        'fixes',\n        'fixed',\n        'resolve',\n        'resolves',\n        'resolved',\n        'refs',\n        'references',\n      ],\n      noteKeywords: ['BREAKING CHANGE', 'SECURITY', 'REMOVED'],\n    },\n    versionFile: 'package.json',\n    bumpVersionFiles: ['package.json', 'package-lock.json'],\n  },\n  log4jsConfig: {\n    appenders: { console: { type: 'console' } },\n    categories: { default: { appenders: ['console'], level: 'info' } },\n  },\n};\n\nconst gitFlow = new AvhGitFlow();\nconst gFlow = new GFlow(gitFlow, gFlowConfig);\n// ...\n```\n\nThe full API documentation can be found [here](https://gitex-flow.github.io/gitex-flow-node/).\n\n# Troubleshooting\n\n1. Executing the `gitex-flow [...]` command results in the following error:\n\n   \u003e _Branches '\\\u003cbranch\u003e' and 'origin/\\\u003cbranch\u003e' have diverged._\n   \u003e\n   \u003e _Fatal: And branch '\\\u003cbranch\u003e' may be fast-forwarded_\n\n   **Reason**: The executed command affects a branch where the local and remote state of the git repository have diverged.\n\n   **Problem**: This problem cannot be solved automatically, because the solution depends heavily on the state of the local git repository.\n\n   **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.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitex-flow%2Fgitex-flow-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgitex-flow%2Fgitex-flow-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitex-flow%2Fgitex-flow-node/lists"}