# Getting Started This document assumes you are familiar with [Conventional Commits](https://www.conventionalcommits.org/) and your git commit messages follow the convention described there. Furthermore it assumes you're using [Semantic Versioning](https://semver.org/) for your project. ## Installation ChangeLog is distributed as [.NET (global) tool](https://docs.microsoft.com/en-us/dotnet/core/tools/global-tools) and requires at least the .NET 6 SDK to be installed (.NET 7 is suppored as well). ChangeLog is available on [NuGet.org](https://www.nuget.org/packages/Grynwald.ChangeLog). Prerelease builds on are available on [MyGet](https://www.myget.org/feed/ap0llo-changelog/package/nuget/Grynwald.ChangeLog). To install ChangeLog, run: ```sh dotnet tool install -g Grynwald.ChangeLog ``` ## Generating a change log ChangeLog assumes you have a local git repository which's commit messages follow the [Conventional Commits](https://www.conventionalcommits.org/) format. The versions of your project are read from the git repository's tags. Versions need to follow the [Semantic Versioning](https://semver.org/) format. By default all tag names that are semantic versions and tag names that are semantic versions prefixed with `v` are recognized (e.g. `1.2.3-alpha` or `v1.2`). Parsing of tags can be customized using the [Tag Patterns Setting](./configuration/settings/tag-patterns.md). To generate a change log from a git repository, run the `changelog generate` command and specify the path to the git repository. ```sh changelog generate --repository <LOCALPATH> ``` The repository path can be omitted when `changelog` is run from a directory within the git repository. > [!IMPORTANT] > changelog needs access to all commits in the git repository and can run into issues with shallow clones. > If you are running changelog in a CI system (like GitHub Actions or Azure Pipelines) make sure to configure your build to **not** use shallow clones. By default, the change log is saved to `changelog.md` in the repository. You can override the output path using the `--outputPath` parameter or in the configuration file (see [Configuration](./configuration.md)). For all full list of commandline parameters, see [Commandline reference](./commandline-reference/index.md) ## Configuration The behavior of ChangeLog can be customized using a configuration file and environment variables. For details, see [Configuration](./configuration.md). ## See Also - [Conventional Commits](https://www.conventionalcommits.org/) - [Semantic Versioning](https://semver.org/) - [Commandline reference](./commandline-reference/index.md) - [Configuration](./configuration.md)