fork-version 5.1.5 → 5.1.7

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Fork Version
 
+## [5.1.7](https://github.com/eglavin/fork-version/compare/v5.1.6...v5.1.7) (2026-05-05)
+
+
+### Refactor
+
+* restructure file managers within source code ([#134](https://github.com/eglavin/fork-version/issues/134)) ([71fedc8](https://github.com/eglavin/fork-version/commit/71fedc87d146222f2320bf0756d8592e67e74290))
+
+
+## [5.1.6](https://github.com/eglavin/fork-version/compare/v5.1.5...v5.1.6) (2026-05-02)
+
+
+### Docs
+
+* split docs out from single readme file ([#133](https://github.com/eglavin/fork-version/issues/133)) ([fb84f0c](https://github.com/eglavin/fork-version/commit/fb84f0c016b834eda248fd0d497bdeb08c748eb6))
+
+
 ## [5.1.5](https://github.com/eglavin/fork-version/compare/v5.1.4...v5.1.5) (2026-04-26)
 
 

package/README.md

@@ -23,7 +23,7 @@ Although there are many alternatives such as <a href=https://github.com/googleap
 By following the [conventional commit](https://www.conventionalcommits.org) standard Fork-Version can automate the following tasks for you:
 
 1. Determine the current and next version
-1. Update the version in the selected files [(View the supported files)](#supported-file-types)
+1. Update the version in the selected files [(View the supported files)](./docs/Supported-File-Managers.md)
 1. Update your changelog
 1. Commit the changed files
 1. Create a tag for the new version
@@ -32,14 +32,11 @@ Fork-Version won't attempt to push changes to git or to a package manager, this
 
 ## Using Fork-Version
 
-Primarily designed to be used with `npx`, Fork-Version can also be installed globally or directly to the node package you're working on. The only software prerequisites you need are [git](https://git-scm.com) and [node](https://nodejs.org).
+Primarily designed to be used with `npx`, Fork-Version can also be installed globally or directly to the node package you're working on. The only software prerequisites you need are [git](https://git-scm.com) and [node](https://nodejs.org) or a node compatible runtime.
 
-Fork-Version can be configured either through a config file or by passing options to the tool when ran, see the [Configuration File](#configuration-file) and [Command Line Options](#command-line-options) sections below for details on the supported options.
+Fork-Version can be configured either through a config file or by passing options to the tool when ran. To see command line options you can run `fork-version --help` or [view the Configuration documentation](./docs/Configuration.md) for details on the supported options and how to use them.
 
-> [!NOTE]
-> Command line options get merged with config file options, any options that are declared through the cli will override options that are also in the config file (Except for the list of [files](#configfiles) which get merged).
-
-### Using `npx` (Recommended)
+### Using `npx`
 
 To use Fork-Version without installation you can use `npx`:
 
@@ -50,9 +47,14 @@ npx fork-version
 `npx` is a package runner which allows you to execute npm packages without installation, this can be useful when working on projects outside of the Node ecosystem.
 
 > [!NOTE]
-> By default `npx` will use the latest release, if you want to use a specific version you can add a version tag to the end of the name.
+> By default `npx` [will use a cached version if available on your system](https://github.com/npm/cli/issues/4108#issuecomment-1022827890) or the latest version otherwise. You can use the `latest` tag to force npx to use the latest version. Alternatively if you want to use a specific version or pin to a range you can add a version tag to the end of the package name:
 >
-> Example: `npx fork-version@1.7.0`
+> - `npx fork-version@5` (Recommended)
+>   - Use the latest version of fork-version in the 5.x range
+> - `npx fork-version@5.1`
+>   - Use the latest version of fork-version in the 5.1.x range
+> - `npx fork-version@5.1.0`
+>   - Use the specific version 5.1.0 of fork-version
 >
 > The version tag needs to match against one of the [published versions on npm](https://www.npmjs.com/package/fork-version?activeTab=versions).
 
@@ -70,8 +72,8 @@ To install the package locally to your project you can use one of the following
 | Package Manager | Install Command                       |
 | --------------- | ------------------------------------- |
 | npm             | `npm install fork-version --save-dev` |
-| yarn            | `yarn add fork-version --dev`         |
 | pnpm            | `pnpm add fork-version --save-dev`    |
+| yarn            | `yarn add fork-version --dev`         |
 | bun             | `bun install fork-version --dev`      |
 
 You can then add the following entry to your package.json scripts section and use it like any other script you already use in your project.
@@ -80,7 +82,7 @@ You can then add the following entry to your package.json scripts section and us
 // package.json
 {
   "scripts": {
-    "release": "fork-version"
+    "release": "fork-version -G \"{*/*.csproj,*/package.json}\""
   }
 }
 ```
@@ -94,7 +96,7 @@ Fork-Version has a number of command modes which will make the program behave di
 | Command             | Description                                                            |
 | ------------------- | ---------------------------------------------------------------------- |
 | `main`              | Bumps the version, update files, generate changelog, commits, and tag. |
-| `inspect`           | Print the current version and git tag, then exit.                       |
+| `inspect`           | Print the current version and git tag, then exit.                      |
 | `inspect-version`   | Print the current version then exit.                                   |
 | `inspect-tag`       | Print the current git tag then exit.                                   |
 | `validate-config`   | Validates the configuration and exit.                                  |
@@ -110,516 +112,18 @@ When ran as a cli tool Fork-Version will exit with one of the following exit cod
 | 2         | Unknown Command              |
 | 3         | Config File Validation Error |
 
-### Command Line Options
-
-The following help text can be viewed by running the following command: `npx fork-version --help`
-
-<!-- START COMMAND LINE OPTIONS -->
-
-```text
-Usage:
-  $ fork-version [command?] [options?]
-
-Commands:
-  main                             Bumps the version, update files, generate changelog, commit, and tag. [Default when no command is provided]
-  inspect                          Print the current version and git tag, then exits.
-  inspect-version                  Print the current version then exits.
-  inspect-tag                      Print the current git tag then exits.
-  validate-config                  Validates the configuration and exits.
-
-General Options:
-  --version                        Show the current version of Fork-Version and exit.
-  --help                           Show this help message and exit.
-
-Location Options:
-  --file, -F                       List of the files to be updated. [Default: ["bower.json", "deno.json", "deno.jsonc", "jsr.json", "jsr.jsonc", "manifest.json", "npm-shrinkwrap.json", "package-lock.json", "package.json"]]
-  --glob, -G                       Glob pattern to match files to be updated.
-  --path, -P                       The path Fork-Version will run from. [Default: process.cwd()]
-
-Options:
-  --changelog                      Name of the changelog file. [Default: "CHANGELOG.md"]
-  --header                         The header text for the changelog.
-  --tag-prefix                     Specify a prefix for the created tag. [Default: "v"]
-  --pre-release                    Mark this release as a pre-release.
-  --pre-release-tag                Mark this release with a tagged pre-release. [Example: "alpha", "beta", "rc"]
-  --current-version                If set, Fork-Version will use this version instead of trying to determine one.
-  --next-version                   If set, Fork-Version will attempt to update to this version, instead of incrementing using "conventional-commit".
-  --release-as                     Release as increments the version by the specified level. [Choices: "major", "minor", "patch"]
-
-Flags:
-  --allow-multiple-versions        Don't throw an error if multiple versions are found in the given files. [Default: true]
-  --commit-all                     Commit all changes, not just files updated by Fork-Version.
-  --changelog-all                  If this flag is set, all default commit types will be added to the changelog.
-  --debug                          Output debug information.
-  --dry-run                        No output will be written to disk or committed.
-  --silent                         Run without logging to the terminal.
-  --git-tag-fallback               If unable to find a version in the given files, fallback and attempt to use the latest git tag. [Default: true]
-  --sign                           If true, git will sign the commit with the systems GPG key.
-  --verify                         If true, git will run user defined git hooks before committing.
-  --as-json                        Output the result as JSON.
-
-  To negate a flag you can prefix it with "no-", for example "--no-git-tag-fallback" will not fallback to the latest git tag.
-
-Skip Steps:
-  --skip-bump                      Skip the version bump step.
-  --skip-changelog                 Skip updating the changelog.
-  --skip-commit                    Skip committing the changes.
-  --skip-tag                       Skip tagging the commit.
-
-Conventional Changelog Overrides:
-  --commit-url-format              Override the default commit URL format.
-  --compare-url-format             Override the default compare URL format.
-  --issue-url-format               Override the default issue URL format.
-  --user-url-format                Override the default user URL format.
-  --release-commit-message-format  Override the default release commit message format.
-  --release-message-suffix         Add a suffix to the end of the release message.
-
-Exit Codes:
-  0: Success
-  1: General Error
-  2: Unknown Command
-  3: Config File Validation Error
-
-Examples:
-  $ fork-version
-    Run fork-version in the current directory with default options.
-
-  $ fork-version --path ./packages/my-package
-    Run fork-version in the "./packages/my-package" directory.
-
-  $ fork-version --file package.json --file MyApi.csproj
-    Run fork-version and update the "package.json" and "MyApi.csproj" files.
-
-  $ fork-version --glob "*/package.json"
-    Run fork-version and update all "package.json" files in subdirectories.
-
-  $ fork-version inspect-version
-    Prints the current version and exits.
-```
-
-<!-- END COMMAND LINE OPTIONS -->
-
-### Configuration File
-
-You can configure Fork-Version using one of the following files:
-
-- [A javascript file](#javascript-config):
-  - fork.config.ts
-  - fork.config.js
-  - fork.config.cjs
-  - fork.config.mjs
-- [A json file](#json-config):
-  - fork.config.json
-  - package.json >> Key Name: "fork-version"
-
-#### Javascript Config
-
-Configuring using a javascript file is the most flexible option. You can use any javascript file type you prefer including typescript. Both commonjs and esm exports styles are supported. The `defineConfig` function in the following snippet is optional, using it will give you intellisense information in your code editor of choice.
-
-```js
-// fork.config.ts
-import { defineConfig } from 'fork-version';
-
-export default defineConfig({
-  header: `# My Changelog`,
-  files: ["package.json", "package-lock.json"],
-});
-```
-
-Alternatively you can use typescript type annotations in a typescript file:
-
-```ts
-// fork.config.ts
-import type { Config } from 'fork-version';
-
-const config: Config = {
-  header: `# My Changelog`,
-  files: ["package.json", "package-lock.json"],
-};
-
-export default config;
-```
-
-Or jsdocs in a javascript file:
-
-```js
-// fork.config.js
-/** @type {import("fork-version").Config} */
-export default {
-  header: `# My Changelog`,
-  files: ["package.json", "package-lock.json"],
-};
-```
-
-Or just raw dog it without type information. ಠ_ಠ
-
-#### Json Config
-
-Another way you can configure Fork-Version is by using a json file called `fork.config.json`. This is a good option if you're using Fork-Version on a non javascript project, or without installation.
-
-If you still want intellisense information you can use the following schema in your json file, otherwise `$schema` is an optional key.
-
-```json
-// fork.config.json
-{
-  "$schema": "https://raw.githubusercontent.com/eglavin/fork-version/main/schema/latest.json",
-  "header": "# My Changelog",
-  "files": [
-    "package.json",
-    "package-lock.json"
-  ]
-}
-```
-
-Internally we're using [zod-to-json-schema](https://github.com/StefanTerdell/zod-to-json-schema) to generate the schema. Checkout the [schema folder](./schema/latest.json) to see the current state.
-
-Alternatively you can define your config using a key in your `package.json` file called `fork-version`:
-
-```json
-// package.json
-{
-  "name": "my-js-project",
-  "version": "1.2.3",
-  "fork-version": {
-    "header": "# My Changelog",
-    "files": [
-      "package.json",
-      "package-lock.json"
-    ]
-  }
-}
-```
-
-#### Config Properties
-
-| Property                                              | Type                 | Default                 | Description                                                                                                         |
-| :---------------------------------------------------- | :------------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------ |
-| command                                               | string               | `main`                  | The command to run. Can be one of: main, inspect-version, inspect-tag, validate-config. Defaults to main.           |
-| [files](#configfiles)                                 | Array\<string>       | `["package.json", ...]` | List of the files to be updated                                                                                     |
-| [customFileManagers](#custom-file-updaters)           | Array\<IFileManager> | -                       | Support for user provided custom file managers                                                                      |
-| [glob](#configglob)                                   | string               | -                       | Glob pattern to match files to be updated                                                                           |
-| path                                                  | string               | `process.cwd()`         | The path Fork-Version will run from                                                                                 |
-| changelog                                             | string               | `CHANGELOG.md`          | Name of the changelog file                                                                                          |
-| header                                                | string               | `# Changelog...`        | The header text for the changelog                                                                                   |
-| [tagPrefix](#configtagprefix)                         | string               | `v`                     | Prefix for the created tag                                                                                          |
-| [preRelease](#configprerelease)                       | string / boolean     | -                       | Make a pre-release with optional label if given value is a string                                                   |
-| currentVersion                                        | string               | -                       | Use this version instead of trying to determine one                                                                 |
-| nextVersion                                           | string               | -                       | Attempt to update to this version, instead of incrementing using "conventional-commit"                              |
-| [releaseAs](#configreleaseas)                         | string               | -                       | Release as increments the version by the specified level. Overrides the default behaviour of "conventional-commit". |
-| allowMultipleVersions                                 | boolean              | true                    | Don't throw an error if multiple versions are found in the given files.                                             |
-| commitAll                                             | boolean              | false                   | Commit all changes, not just files updated by Fork-Version                                                          |
-| changelogAll                                          | boolean              | false                   | If this flag is set, all default commit types will be added to the changelog, not just `feat` and `fix`.            |
-| debug                                                 | boolean              | false                   | Output debug information                                                                                            |
-| dryRun                                                | boolean              | false                   | No output will be written to disk or committed                                                                      |
-| silent                                                | boolean              | false                   | Run without logging to the terminal                                                                                 |
-| gitTagFallback                                        | boolean              | true                    | If unable to find a version in the given files, fallback and attempt to use the latest git tag                      |
-| sign                                                  | boolean              | false                   | Sign the commit with the systems GPG key                                                                            |
-| verify                                                | boolean              | false                   | Run user defined git hooks before committing                                                                        |
-| asJson                                                | boolean              | false                   | Print inspected output as a parsable json string                                                                    |
-| skipBump                                              | boolean              | false                   | Skip the bump step                                                                                                  |
-| skipChangelog                                         | boolean              | false                   | Skip the changelog step                                                                                             |
-| skipCommit                                            | boolean              | false                   | Skip the commit step                                                                                                |
-| skipTag                                               | boolean              | false                   | Skip the tag step                                                                                                   |
-| [changelogPresetConfig](#configchangelogpresetconfig) | object               | {}                      | Override defaults from the "conventional-changelog-conventionalcommits" preset configuration                        |
-| releaseMessageSuffix                                  | string               | -                       | Add a suffix to the end of the release message                                                                      |
-| [commitParserOptions](#configcommitparseroptions)     | object               | {}                      | Options to pass to commits parser                                                                                   |
-
-##### config.files
-
-By default Fork-Version will attempt to read versions from and update these files, if you define your own list it will override the default list instead of merging.
-
-- "package.json"
-- "package-lock.json"
-- "npm-shrinkwrap.json"
-- "jsr.json"
-- "jsr.jsonc"
-- "deno.json"
-- "deno.jsonc"
-- "manifest.json"
-- "bower.json"
-
-See the [Supported File Types](#supported-file-types) section below to see the currently supported file types and the [Custom File Updater's](#custom-file-updaters) section below to see how to support other file types.
-
-##### config.glob
-
-An alternative to [config.files](#configfiles), a glob allows you to search for files using wildcard characters.
-
-For example if you have the following folder structure:
-
-```text
-API/
-- MyAPI.csproj
-Library/
-- MyLibrary.csproj
-Web/
-- package.json
-```
-
-Running `npx fork-version -G "{*/*.csproj,*/package.json}"` will update both csproj files and the package.json file.
-
-Internally Fork-Version uses [isaacs glob](https://github.com/isaacs/node-glob) to match files. Read more about the pattern syntax [here](https://github.com/isaacs/node-glob/tree/v10.3.12?tab=readme-ov-file#glob-primer).
-
-> [!WARNING]
-> Ensure you wrap your glob pattern in quotes to prevent shell expansion.
-
-##### config.tagPrefix
-
-Allows you to control the prefix for the created tag. This is useful if your using a mono-repo in which you version multiple projects separately or simply want to use a different prefix for your tags.
-
-| Example Value            | Tag Created                   |
-|:-------------------------|:------------------------------|
-| "v" (Default)            | `v1.2.3`                      |
-| ""                       | `1.2.3`                       |
-| "version/"               | `version/1.2.3`               |
-| "@eglavin/fork-version-" | `@eglavin/fork-version-1.2.3` |
-
-##### config.preRelease
-
-Marking a release as a pre-release allows you to define a change as a patch to a specific version. This allows you to mark a fix for a version or an alpha build for example.
-
-| Example Value | Version Created |
-|:--------------|:----------------|
-| `true`        | `1.2.3-0`       |
-| `alpha`       | `1.2.3-alpha.0` |
-
-Fork-Version uses [meow](https://github.com/sindresorhus/meow) to parse cli arguments which is unable to take a single argument and parse it as either a string and or a boolean. So to do the above through the cli interface you'll need to use two different arguments:
-
-| Example CLI Usage                      | Version Created |
-|:---------------------------------------|:----------------|
-| `fork-version --pre-release`           | `1.2.3-0`       |
-| `fork-version --pre-release-tag alpha` | `1.2.3-alpha.0` |
-
-##### config.releaseAs
-
-Allows you to override the default versioning behaviour of Fork-Version and increment by the specified level. For example if the current version is `1.2.3` and you run Fork-Version with one of the following arguments, the version will be incremented as shown below.
-
-| Example Value | Version Created |
-|:--------------|:----------------|
-| `major`       | 2.0.0           |
-| `minor`       | 1.3.0           |
-| `patch`       | 1.2.4           |
-
-##### config.changelogPresetConfig
-
-Fork-Version uses the [conventional changelog config spec](https://github.com/conventional-changelog/conventional-changelog-config-spec). The following is an excerpt of the configurable options.
-
-| Property                                   | Type           | Default                                                                      | Description                                                             |
-|:-------------------------------------------|:---------------|:-----------------------------------------------------------------------------|:------------------------------------------------------------------------|
-| [types](#configchangelogpresetconfigtypes) | Array\<Type>   | {}                                                                           | List of explicitly supported commit message types                       |
-| commitUrlFormat                            | string         | `{{host}}/{{owner}}/{{repository}}/commit/{{hash}}`                          | A URL representing a specific commit at a hash                          |
-| compareUrlFormat                           | string         | `{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}` | A URL representing the comparison between two git SHAs                  |
-| issueUrlFormat                             | string         | `{{host}}/{{owner}}/{{repository}}/issues/{{id}}`                            | A URL representing the issue format                                     |
-| userUrlFormat                              | string         | `{{host}}/{{user}}`                                                          | A URL representing a user's profile                                     |
-| releaseCommitMessageFormat                 | string         | `chore(release): {{currentTag}}`                                             | A string to be used to format the auto-generated release commit message |
-| issuePrefixes                              | Array\<string> | `["#"]`                                                                      | List of prefixes used to detect references to issues                    |
-
-###### config.changelogPresetConfig.types
-
-By default only `feat` and `fix` commits are added to your changelog, you can configure extra sections to show by modifying this section.
-
-Checkout the `fork.config.js` file [here](./fork.config.js) to see an example of modifying the types.
-
-| Property | Type    | Description                                                              |
-|:---------|:--------|:-------------------------------------------------------------------------|
-| type     | string  | The type of commit message. "feat", "fix", "chore", etc..                |
-| scope    | string  | The scope of the commit message.                                         |
-| section  | string  | The name of the section in the `CHANGELOG` the commit should show up in. |
-| hidden   | boolean | Should show in the generated changelog message?                          |
+### Supported File Managers
 
-##### config.releaseMessageSuffix
+Fork-Version supports a number of built in file managers for popular file types, the following file types are supported out of the box:
 
-Adds a suffix to the end of the release message, useful to add a `[skip ci]` message to the end of the created commit.
-
-- [GitHub Actions - Skipping workflow runs](https://docs.github.com/en/actions/managing-workflow-runs/skipping-workflow-runs)
-- [Azure Devops - Skipping CI for individual pushes](https://learn.microsoft.com/en-us/azure/devops/pipelines/repos/azure-repos-git?view=azure-devops&tabs=yaml#skipping-ci-for-individual-pushes)
-
-##### config.commitParserOptions
-
-The commit parser options allow you to configure the regex patterns used to parse commits. This is useful if your team has a specific commit message format that doesn't match the default conventional commit format.
-
-| Property               | Type           | Description                                       |
-| :--------------------- | :------------- | :------------------------------------------------ |
-| subjectPattern         | Regex          | Pattern to match commit subjects                  |
-| mergePattern           | Regex          | Pattern to match merge commits                    |
-| revertPattern          | Regex          | Pattern to match revert commits                   |
-| commentPattern         | Regex          | Pattern to match commented out lines              |
-| mentionPattern         | Regex          | Pattern to match mentions                         |
-| referenceActions       | Array\<string> | List of action labels to match reference sections |
-| referenceActionPattern | Regex          | Pattern to match reference sections               |
-| issuePrefixes          | Array\<string> | List of issue prefixes to match issue ids         |
-| issuePattern           | Regex          | Pattern to match issue references                 |
-| noteKeywords           | Array\<string> | List of keywords to match note titles             |
-| notePattern            | Regex          | Pattern to match note sections                    |
-
-[View the commit parser options to see the default patterns used.](./src/commit-parser/options.ts)
-
-If you are using one of the following Git hosts, Fork-Version will automatically use the correct commit parser options for that host:
-
-- GitHub
-- GitLab
-- BitBucket
-- Azure DevOps
-
-[View the `detect-git-host` function to see how Fork-Version detects the git host.](./src/detect-git-host/detect-git-host.ts)
-
-### Supported File Types
-
-- [Json Package](#json-package)
-- [Yaml Package](#yaml-package)
-- [Plain Text](#plain-text)
-- [MS Build](#ms-build)
-- [ARM Bicep](#arm-bicep)
-- [Install Shield ISM](#install-shield-ism)
-- [Custom File Updater's](#custom-file-updaters)
-
-> [!Note]
-> If your version strings include build metadata like one of the following examples:
->
-> - 1.2.3+49a3f2b
-> - 1.2.3-0+49a3f2b
-> - 1.2.3-alpha.0+49a3f2b
->
-> this metadata will be retained without modification.
-
-#### Json Package
-
-A json package is a json file which contains a version property, such as a npm package.json file.
-
-```json
-{
-  "name": "my-project",
-  "version": "1.2.3",
-  "private": false,
-}
-```
-
-#### Yaml Package
-
-A yaml package is a yaml file which contains a version property, such as a dart pubspec.yaml file.
-
-```yaml
-name: wordionary
-description: "My project"
-publish_to: 'none'
-version: 1.2.3
-```
-
-#### Plain Text
-
-A plain text file is a file which contains just the version as the content. Files that end with `version.txt` will be treated as a plain text version file.
-
-```text
-1.2.3
-```
-
-#### MS Build
-
-A MS build project is an xml file with with a `Version` property under the `Project > PropertyGroup` node group.
-
-```xml
-<Project Sdk="Microsoft.NET.Sdk">
-  <PropertyGroup>
-    <Version>1.2.3</Version>
-  </PropertyGroup>
-</Project>
-```
-
-Fork-Version currently supports reading and updating the following file extensions: `.csproj` `.dbproj` `.esproj` `.fsproj` `.props` `.vbproj` `.vcxproj`
-
-#### ARM Bicep
-
-An ARM bicep file with metadata and variable called contentVersion.
-
-```bicep
-metadata contentVersion = '1.2.3.4'
-var contentVersion string = '1.2.3.4'
-```
-
-#### Install Shield ISM
-
-An Install Shield `*.ism` file can be either binary or an xml file. Fork-Version only supports the xml version.
-
-```xml
-<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<?xml-stylesheet type="text/xsl" href="is.xsl" ?>
-<!DOCTYPE msi [...]>
-<msi version="2.0" xmlns:dt="urn:schemas-microsoft-com:datatypes">
-
-  <table name="Property">
-    <row><td>ProductVersion</td><td>1.2.3</td><td/></row>
-  </table>
-
-</msi>
-```
-
-#### Custom File Updater's
-
-***Released in version 5.1.0***
-
-If you have a file type that isn't supported by default, you can create a custom file manager to read and write the updated version to that file.
-
-To do this you will need to create a class or an object that implements the `IFileManager` interface and add an instance of that class or object to the `customFileManagers` array in your config.
-
-The following example show a custom file manager for a json file with the name of `test.json` with the following structure:
-
-Example `test.json` file:
-
-```json
-{
-  "package": {
-    "version": "1.2.3"
-  }
-}
-```
-
-Example Custom File Manager implementation:
-
-- [Using a class to define a file manager](./examples/custom-file-manager/fork.config.ts)
-- [Using the defineFileManager function](./examples/custom-file-manager/fork.config.defineFileManager.ts)
-
-```ts
-// fork.config.ts
-import { readFile, writeFile } from "node:fs/promises";
-import { defineConfig, MissingPropertyException, type FileState, type IFileManager } from "fork-version";
-
-class CustomFileManager implements IFileManager {
-  async read(filePath: string): Promise<FileState | undefined> {
-    const fileContent = await readFile(filePath, "utf-8");
-    if (fileContent) {
-      const parsedContent = JSON.parse(fileContent);
-      if ("package" in parsedContent && "version" in parsedContent.package) {
-        return {
-          path: filePath,
-          version: parsedContent.package.version,
-        };
-      }
-    }
-    throw new MissingPropertyException("My Custom File", "package.version");
-  }
-
-  async write(fileState: FileState, newVersion: string): Promise<void> {
-    const fileContent = await readFile(fileState.path, "utf-8");
-    if (fileContent) {
-      const parsedContent = JSON.parse(fileContent);
-      if ("package" in parsedContent && "version" in parsedContent.package) {
-        parsedContent.package.version = newVersion;
-        const updatedContent = JSON.stringify(parsedContent, null, 2);
-        await writeFile(fileState.path, updatedContent, "utf-8");
-      }
-    }
-  }
-
-  isSupportedFile(fileName: string) {
-    return fileName === "test.json";
-  }
-}
-
-export default defineConfig({
-  customFileManagers: [new CustomFileManager()],
-});
-```
+- [Json Package](./docs/Supported-File-Managers.md#json-package)
+- [Yaml Package](./docs/Supported-File-Managers.md#yaml-package)
+- [Plain Text](./docs/Supported-File-Managers.md#plain-text)
+- [MS Build](./docs/Supported-File-Managers.md#ms-build)
+- [ARM Bicep](./docs/Supported-File-Managers.md#arm-bicep)
+- [Install Shield ISM](./docs/Supported-File-Managers.md#install-shield-ism)
 
-> [See `IFileManager` interface to see the required methods and properties for a custom file manager.](./src/files/file-manager.ts)
+[Read more about the supported file managers and how to create your own custom file managers.](./docs/Supported-File-Managers.md)
 
 ### Code Usage
 

package/dist/cli.js

@@ -4,7 +4,7 @@ import { main } from "./commands/main.js";
 import { validateConfig } from "./commands/validate-config.js";
 import { Git } from "./services/git.js";
 import { getUserConfig } from "./config/user-config.js";
-import { FileManager } from "./files/file-manager.js";
+import { FileManager } from "./services/file-manager.js";
 import { Logger } from "./services/logger.js";
 import { getCliArguments } from "./config/cli-arguments.js";
 import { join } from "node:path";

package/dist/commands/inspect.d.ts

@@ -1,5 +1,5 @@
 import { Logger } from "../services/logger.js";
-import { FileManager } from "../files/file-manager.js";
+import { FileManager } from "../services/file-manager.js";
 import { ForkConfig } from "../config/types.js";
 import { Git } from "../services/git.js";
 

package/dist/commands/main.d.ts

@@ -1,5 +1,5 @@
 import { Logger } from "../services/logger.js";
-import { FileManager } from "../files/file-manager.js";
+import { FileManager } from "../services/file-manager.js";
 import { ForkConfig } from "../config/types.js";
 import { Git } from "../services/git.js";
 import { CommitsSinceTag } from "../process/get-commits.js";

package/dist/config/define-config.d.ts

@@ -2,7 +2,22 @@ import { Config } from "./types.js";
 
 //#region src/config/define-config.d.ts
 /**
- * [Fork-Version - Config Properties](https://github.com/eglavin/fork-version/blob/main/README.md#config-properties)
+ * Optional helper function to enable intellisense and type checking when defining a Fork-Version configuration object.
+ *
+ * [Fork-Version - Config Options](https://github.com/eglavin/fork-version/blob/main/docs/Configuration.md#config-options)
+ *
+ * @example
+ * ```ts
+ * // File: fork.config.ts
+ * import { defineConfig } from "fork-version";
+ *
+ * export default defineConfig({
+ *   header: "# Changelog\n\nMy Custom Changelog Header",
+ * });
+ * ```
+ *
+ * @param config The configuration object to be defined.
+ * @returns The same configuration object that was passed in.
  */
 declare function defineConfig(config: Config): Config;
 //#endregion

package/dist/config/define-config.js

@@ -1,6 +1,21 @@
 //#region src/config/define-config.ts
 /**
-* [Fork-Version - Config Properties](https://github.com/eglavin/fork-version/blob/main/README.md#config-properties)
+* Optional helper function to enable intellisense and type checking when defining a Fork-Version configuration object.
+*
+* [Fork-Version - Config Options](https://github.com/eglavin/fork-version/blob/main/docs/Configuration.md#config-options)
+*
+* @example
+* ```ts
+* // File: fork.config.ts
+* import { defineConfig } from "fork-version";
+*
+* export default defineConfig({
+*   header: "# Changelog\n\nMy Custom Changelog Header",
+* });
+* ```
+*
+* @param config The configuration object to be defined.
+* @returns The same configuration object that was passed in.
 */
 function defineConfig(config) {
 	return config;

package/dist/config/define-file-manager.d.ts

@@ -0,0 +1,42 @@
+import { IFileManager } from "../services/file-manager.js";
+
+//#region src/config/define-file-manager.d.ts
+/**
+ * Optional helper function to enable intellisense and type checking when defining a custom file manager.
+ *
+ * [Fork-Version - Custom File Managers](https://github.com/eglavin/fork-version/blob/main/docs/Supported-File-Managers.md#custom-file-updaters)
+ *
+ *
+ * @example
+ * ```ts
+ * // File: fork.config.ts
+ * import { defineFileManager } from "fork-version";
+ *
+ * const myFileManager = defineFileManager({
+ *   async read(filePath) {
+ *     // Logic to read the file and extract the version.
+ *     return {
+ *       path: "/path/to/file",
+ *       version: "1.2.3",
+ *     };
+ *   },
+ *   async write(fileState, newVersion) {
+ *     // Logic to write the updated version.
+ *   },
+ *   isSupportedFile(fileName) {
+ *     // Logic to determine if the file is supported by this file manager.
+ *     return fileName.endsWith(".custom");
+ *   },
+ * });
+ *
+ * export default {
+ *   customFileManagers: [myFileManager],
+ * }
+ * ```
+ *
+ * @param fileManager The custom file manager to be defined.
+ * @returns The same file manager object that was passed in.
+ */
+declare function defineFileManager(fileManager: IFileManager): IFileManager;
+//#endregion
+export { defineFileManager };

package/dist/config/define-file-manager.js

@@ -0,0 +1,42 @@
+//#region src/config/define-file-manager.ts
+/**
+* Optional helper function to enable intellisense and type checking when defining a custom file manager.
+*
+* [Fork-Version - Custom File Managers](https://github.com/eglavin/fork-version/blob/main/docs/Supported-File-Managers.md#custom-file-updaters)
+*
+*
+* @example
+* ```ts
+* // File: fork.config.ts
+* import { defineFileManager } from "fork-version";
+*
+* const myFileManager = defineFileManager({
+*   async read(filePath) {
+*     // Logic to read the file and extract the version.
+*     return {
+*       path: "/path/to/file",
+*       version: "1.2.3",
+*     };
+*   },
+*   async write(fileState, newVersion) {
+*     // Logic to write the updated version.
+*   },
+*   isSupportedFile(fileName) {
+*     // Logic to determine if the file is supported by this file manager.
+*     return fileName.endsWith(".custom");
+*   },
+* });
+*
+* export default {
+*   customFileManagers: [myFileManager],
+* }
+* ```
+*
+* @param fileManager The custom file manager to be defined.
+* @returns The same file manager object that was passed in.
+*/
+function defineFileManager(fileManager) {
+	return fileManager;
+}
+//#endregion
+export { defineFileManager };

package/dist/config/types.d.ts

@@ -1,6 +1,6 @@
 import { getCliArguments } from "./cli-arguments.js";
 import { ParserOptions } from "../commit-parser/options.js";
-import { IFileManager } from "../files/file-manager.js";
+import { IFileManager } from "../services/file-manager.js";
 
 //#region src/config/types.d.ts
 interface ChangelogPresetConfigType {

package/dist/{files → file-managers}/arm-bicep.js

@@ -1,6 +1,6 @@
-import { MissingPropertyException } from "./file-manager.js";
+import { MissingPropertyException } from "../services/file-manager.js";
 import { readFile, writeFile } from "node:fs/promises";
-//#region src/files/arm-bicep.ts
+//#region src/file-managers/arm-bicep.ts
 /**
 * An ARM bicep file with metadata and variable called contentVersion.
 *

package/dist/{files → file-managers}/install-shield-ism.js

@@ -1,7 +1,7 @@
-import { MissingPropertyException } from "./file-manager.js";
+import { MissingPropertyException } from "../services/file-manager.js";
 import { readFile, writeFile } from "node:fs/promises";
 import * as cheerio from "cheerio/slim";
-//#region src/files/install-shield-ism.ts
+//#region src/file-managers/install-shield-ism.ts
 /**
 * An InstallShield ISM file can be either XML or binary, only the XML format is supported
 * by this file manager. The XML format typically contains a "Property" table with a

package/dist/{files → file-managers}/json-package.js

@@ -1,7 +1,7 @@
-import { MissingPropertyException } from "./file-manager.js";
+import { MissingPropertyException } from "../services/file-manager.js";
 import { readFile, writeFile } from "node:fs/promises";
 import { applyEdits, modify, parse } from "jsonc-parser";
-//#region src/files/json-package.ts
+//#region src/file-managers/json-package.ts
 /**
 * A json package file should have a version property, like what can be seen
 * in the package.json file in the root of this project.

package/dist/{files → file-managers}/ms-build-project.js

@@ -1,7 +1,7 @@
-import { MissingPropertyException } from "./file-manager.js";
+import { MissingPropertyException } from "../services/file-manager.js";
 import { readFile, writeFile } from "node:fs/promises";
 import * as cheerio from "cheerio/slim";
-//#region src/files/ms-build-project.ts
+//#region src/file-managers/ms-build-project.ts
 /**
 * A ms-build file is an xml file with a version property under the Project > PropertyGroup node.
 *

package/dist/{files → file-managers}/plain-text.js

@@ -1,6 +1,6 @@
-import { MissingPropertyException } from "./file-manager.js";
+import { MissingPropertyException } from "../services/file-manager.js";
 import { readFile, writeFile } from "node:fs/promises";
-//#region src/files/plain-text.ts
+//#region src/file-managers/plain-text.ts
 /**
 * A plain text file will have just the version as the content.
 *

package/dist/{files → file-managers}/yaml-package.js

@@ -1,7 +1,7 @@
-import { MissingPropertyException } from "./file-manager.js";
+import { MissingPropertyException } from "../services/file-manager.js";
 import { readFile, writeFile } from "node:fs/promises";
 import { parse, parseDocument } from "yaml";
-//#region src/files/yaml-package.ts
+//#region src/file-managers/yaml-package.ts
 /**
 * A yaml package file should have a version property on the top level, like what can be seen
 * in [this example project](https://github.com/eglavin/wordionary/blob/01ae9b9d604cecdf9d320ed6028a727be5e5349e/pubspec.yaml#L19C1-L19C17).

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { ParserOptions, createParserOptions } from "./commit-parser/options.js";
 import { Logger } from "./services/logger.js";
-import { FileManager, FileState, IFileManager, MissingPropertyException, defineFileManager } from "./files/file-manager.js";
+import { FileManager, FileState, IFileManager, MissingPropertyException } from "./services/file-manager.js";
 import { ChangelogPresetConfig, ChangelogPresetConfigType, Config, ForkConfig } from "./config/types.js";
 import { Git } from "./services/git.js";
 import { inspect } from "./commands/inspect.js";
@@ -11,6 +11,7 @@ import { CommitParser } from "./commit-parser/commit-parser.js";
 import { filterRevertedCommits } from "./commit-parser/filter-reverted-commits.js";
 import { ForkConfigJSONSchema, ForkConfigJSSchema } from "./config/schema.js";
 import { defineConfig } from "./config/define-config.js";
+import { defineFileManager } from "./config/define-file-manager.js";
 import { getUserConfig } from "./config/user-config.js";
 import { CommitsSinceTag, getCommitsSinceTag } from "./process/get-commits.js";
 import { CurrentVersion, getCurrentVersion } from "./process/get-current-version.js";

package/dist/index.js

@@ -12,8 +12,9 @@ import { main } from "./commands/main.js";
 import { validateConfig } from "./commands/validate-config.js";
 import { ForkConfigJSONSchema, ForkConfigJSSchema } from "./config/schema.js";
 import { defineConfig } from "./config/define-config.js";
+import { defineFileManager } from "./config/define-file-manager.js";
 import { Git } from "./services/git.js";
 import { getUserConfig } from "./config/user-config.js";
-import { FileManager, MissingPropertyException, defineFileManager } from "./files/file-manager.js";
+import { FileManager, MissingPropertyException } from "./services/file-manager.js";
 import { Logger } from "./services/logger.js";
 export { CommitParser, FileManager, ForkConfigJSONSchema, ForkConfigJSSchema, Git, Logger, MissingPropertyException, commitChanges, createParserOptions, defineConfig, defineFileManager, filterRevertedCommits, getCommitsSinceTag, getCurrentVersion, getNextVersion, getUserConfig, inspect, main, tagChanges, updateChangelog, validateConfig };

package/dist/process/commit.d.ts

@@ -1,5 +1,5 @@
 import { Logger } from "../services/logger.js";
-import { FileState } from "../files/file-manager.js";
+import { FileState } from "../services/file-manager.js";
 import { ForkConfig } from "../config/types.js";
 import { Git } from "../services/git.js";
 

package/dist/process/get-current-version.d.ts

@@ -1,5 +1,5 @@
 import { Logger } from "../services/logger.js";
-import { FileManager, FileState } from "../files/file-manager.js";
+import { FileManager, FileState } from "../services/file-manager.js";
 import { ForkConfig } from "../config/types.js";
 import { Git } from "../services/git.js";
 

package/dist/{files → services}/file-manager.d.ts

@@ -1,7 +1,7 @@
-import { Logger } from "../services/logger.js";
+import { Logger } from "./logger.js";
 import { ForkConfig } from "../config/types.js";
 
-//#region src/files/file-manager.d.ts
+//#region src/services/file-manager.d.ts
 /**
  * Exception thrown if a file manager encounters a file missing a required property,
  * such as the "version" property in a JSON package file.
@@ -61,12 +61,6 @@ interface IFileManager {
    */
   isSupportedFile(filePath: string): boolean;
 }
-/**
- * Helper function to define a custom file manager with proper typing.
- *
- * [Fork-Version - Custom File Managers](https://github.com/eglavin/fork-version#custom-file-updaters)
- */
-declare function defineFileManager(fileManager: IFileManager): IFileManager;
 declare class FileManager {
   #private;
   constructor(config: ForkConfig, logger: Logger);
@@ -96,4 +90,4 @@ declare class FileManager {
   write(fileState: FileState, newVersion: string): Promise<void>;
 }
 //#endregion
-export { FileManager, FileState, IFileManager, MissingPropertyException, defineFileManager };
+export { FileManager, FileState, IFileManager, MissingPropertyException };

package/dist/{files → services}/file-manager.js

@@ -1,13 +1,13 @@
 import { fileExists } from "../utils/file-state.js";
-import { JSONPackage } from "./json-package.js";
-import { YAMLPackage } from "./yaml-package.js";
-import { PlainText } from "./plain-text.js";
-import { MSBuildProject } from "./ms-build-project.js";
-import { ARMBicep } from "./arm-bicep.js";
-import { InstallShieldISM } from "./install-shield-ism.js";
+import { JSONPackage } from "../file-managers/json-package.js";
+import { YAMLPackage } from "../file-managers/yaml-package.js";
+import { PlainText } from "../file-managers/plain-text.js";
+import { MSBuildProject } from "../file-managers/ms-build-project.js";
+import { ARMBicep } from "../file-managers/arm-bicep.js";
+import { InstallShieldISM } from "../file-managers/install-shield-ism.js";
 import { extractBuildMetadata } from "../utils/extract-build-metadata.js";
 import { isAbsolute, relative, resolve } from "node:path";
-//#region src/files/file-manager.ts
+//#region src/services/file-manager.ts
 /**
 * Exception thrown if a file manager encounters a file missing a required property,
 * such as the "version" property in a JSON package file.
@@ -22,14 +22,6 @@ var MissingPropertyException = class extends Error {
 		this.propertyName = propertyName;
 	}
 };
-/**
-* Helper function to define a custom file manager with proper typing.
-*
-* [Fork-Version - Custom File Managers](https://github.com/eglavin/fork-version#custom-file-updaters)
-*/
-function defineFileManager(fileManager) {
-	return fileManager;
-}
 var FileManager = class {
 	#config;
 	#logger;
@@ -105,4 +97,4 @@ var FileManager = class {
 	}
 };
 //#endregion
-export { FileManager, MissingPropertyException, defineFileManager };
+export { FileManager, MissingPropertyException };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fork-version",
-  "version": "5.1.5",
+  "version": "5.1.7",
   "license": "MIT",
   "description": "Fork-Version automates version control tasks such as determining, updating, and committing versions, files, and changelogs, simplifying the process when adhering to the conventional commit standard.",
   "keywords": [