-
-
-
commits to changelogs
- -[](https://goreportcard.com/report/github.com/barelyhuman/commitlog) - -## Philosophy - -- Work on all major operating systems -- Not platform dependent, not tied to Github, Gitlab, or anything. It's just markdown. -- Ability to generate change logs between version tags -- Handle release versioning of the project -- Stay small - -## Installation - - -### Using [goblin.run](https://goblin.run) -```sh -; curl -sfL https://goblin.run/github.com/barelyhuman/commitlog/v3 | sh -``` - -### go -If you have go installed, you can use the below command - -```sh -go install github.com/barelyhuman/commitlog/v3@latest -``` - -## Why - -Every language has it's own isolated version of a tool like this, for someone who works with multiple languages, it's easier to -have the same tool working everywhere, without having to setup something get it working. There's an even tighter scoped version of this, [nimclog](https://github.com/barelyhuman/nimclog). - -The point of the tool is not to create super descriptive changelogs for you but to help your changelogs have enough information for you as a developer to be able to write proper changelogs while having references to the changes in one place. - -## Documentation - -The documentation can be read from the `docs` folder of the repository, or on the [website](https://barelyhuman.github.io/commitlog) - -## License - -[MIT](/LICENSE) diff --git a/api.html b/api.html new file mode 100644 index 0000000..9f341f8 --- /dev/null +++ b/api.html @@ -0,0 +1,64 @@ +commitlog also comes as a pkg that you could reuse to modify the behaviour of +the commands and this is very limited at the moment since I'm still working on +the best way to get plugins to work with the original CLI instead of having to +write your own version of commitlog.
+The pkg contains the 2 base command's creators and behaviour modifiers, or more +commonly known as the golang options pattern.
+Briefly put, You have one function that takes in unlimited amount of functions +as parameter with each of these parameter functions being able to modify the +behaviour of the returned instance.
+Easy way to explain this is with an example of the releaser API
package main
+
+import (
+ "log"
+
+ "github.com/barelyhuman/commitlog/v3/pkg"
+)
+
+func main() {
+ versionString := "v0.0.1"
+ releaser, _ := pkg.CreateNewReleaser(
+ versionString,
+ pkg.WithMajorIncrement(),
+ )
+
+ log.Println(releaser.String())
+
+}
+here the pkg.CreateNewReleaser takes in one mandatory value which is the
+versionString and the 2nd parameter is optional here.
Though, since we wish for the releaser to have a custom behaviour everytime the +flags change, instead of writing entire functionalities inside various releaser +functions, which would look like so
+releaser.IncrementMajor()
+releaser.IncrementMinor()
+I'd be unable to expose the builders / option functions out to the public for
+them to write custom behaviours that work directly with the struct being used
+by commitlog itself and instead you'd be writing wrappers around existing
+functions. Thus, adding another layer of abstraction which isn't needed for
+something that wants to be extended.
This approach gives me the ability to expose a selected few properties for you +to modify while writing your own builder/option function.
+The only pointer functions that releaser has is the one's that'll help with +printing or identifying the final version's state.
+Since, you now know how the API is written, the go doc for this module should be +able to help you with the remaining.
+ +++Note: if the go doc still hasn't been generated for v2.0.0, please go +through the source code to help you with the implementation details
+
commitlog-v3.0.0-darwin-amd64.tar.gz
+commitlog-v3.0.0-darwin-amd64.tar.gz.md5
+commitlog-v3.0.0-darwin-arm64.tar.gz
+commitlog-v3.0.0-darwin-arm64.tar.gz.md5
+commitlog-v3.0.0-linux-386.tar.gz
+commitlog-v3.0.0-linux-386.tar.gz.md5
+commitlog-v3.0.0-linux-amd64.tar.gz
+commitlog-v3.0.0-linux-amd64.tar.gz.md5
+commitlog-v3.0.0-linux-arm64.tar.gz
+commitlog-v3.0.0-linux-arm64.tar.gz.md5
+commitlog-v3.0.0-windows-386.zip
+commitlog-v3.0.0-windows-386.zip.md5
+commitlog-v3.0.0-windows-amd64.zip
+commitlog-v3.0.0-windows-amd64.zip.md5
For the one's who already know the tool and wanna get started quickly.
+You can get the CLI in the following ways
+You can get the binaries from the download section
+Using go get
go get -u github.com/barelyhuman/commitlog/v3
+curl -sf https://goblin.run/github.com/barelyhuman/commitlog/v3@v3 | sh
+Once installed you can just run commitlog generate or the shorter version
+commitlog g to get all the changes between the recent tags.
commitlog simply exists because I wasn't able to find a decent enough tool
+to do this without being bound to a specific programming language and it's
+toolset. The closes one to this is the git's own shortlog and log commands
Language Agnostic - No one needs the entire programming toolset or the +language to be setup on the system to be able to just generate logs
+Decently Sized - Not everyone has a powerful system and CI systems are +still very limited in terms of resources since they give you shared spaces and +automating generating this is a common practice so it doesn't make sense for +it to install a runtime worth 100MB to run it.
+The binary itself is around 10-13MB which is fairly big for a tool like this +but this is due to go's nature of embedding the platform runtime with the +binary and this might not be ideal for some and so there's another similar +smaller scoped version nimclog which +is in KB's
+Flexible - There are no set standards for how you write commit messages. +Commitlint is a good standard and pretty widely used and also what commitlog +v1 used as the base for categorizing.
+V2 however, doesn't have a set commit category standard, it accepts regex's +that you will categorize your commits for you.
+This is more for experienced developers who have a their own pattern of +writing commits and would like a tool that'd work with their pattern instead +of creating friction
+Extensible - The entire thing is open source and MIT licenses,
+specifically for you to be able to fix and add things as needed. Each command
+has been kept away from the domain logic to be able to use commitlog even as
+a library and build your own tool if you wish to, though if there's something
+you wish the CLI supported, you are free to open issues and I really like
+people helping with the development since that helps keeping the tool alive
+longer.
The installation is pretty straightforwad. You download the binary +from the download section of this website or use something like +goblin to build the binary for your specific +system (rarely needed) since the releases actually accommodate the most used +operating systems and architectures already.
+Linux/Mac (Unix Systems)
+Once downloaded, you can use the install command on *nix systems to link the
+binary to a location that's already in your PATH variable.
eg:
+# install commitlog from current directory to the /usr/local/bin directory
+install $(pwd)/commitlog /usr/local/bin
+This should give you the ability to use the commitlog command anywhere in your
+system
Windows
+Similar to the linux setup, you can download the .exe file and add it to a
+location that your environment path already has. An easier thing to do is to
+store the entire thing in your secondary partition and add that location to your
+PATH. You can use this resource from Java docs to help you with modifying the
+PATH variables
commitlog is MIT Licensed and you can read the entire license in the +source code
+commitlog come with 2 basic functionalities
Both the above are available as sub commands and we'll go through each one by +one.
+Just running commitlog no longer works as it did in v1, you'll need to specify
+a sub command to get it working.
This has been done to keep it simpler to keep arbitrary behaviour to a minimum
+The first one is generate and in most cases you'll just be using this to
+handle generation of commits as a list of markdown notes
Here's an example of what it'll look like to run the generate sub-command
$ commitlog generate
+# or
+$ commitlog g
+Output:
+## All Changes
+87ce3fc76b252908cdd81f9537713f8d67813652 chore: v2.0.0-beta.0
+
+09fc85c0d1d52d770bbbf39ac45907103a53d354 refactor: swap go-git for push with exec
+
+5bafe9d105298001707c7c816e60d3ef0257a816 fix: tag creation
+
+909fd032facdeb4fb7633a4fad82dced28e8de83 chore: swap debugging logger with stderr printer
+<!-- .... more commits till the end of tag -->
+The behaviour of the generate command is like so
go through all commits from the current HEAD (commit with the HEAD
+reference) till the last commit or the most recent tagged commit.
the other case is where if the latest commit is also a tagged commit, it'll +still go till the most recent tagged commit.
+eg: v0.0.2 -> HEAD, v0.0.1 -> SOMEHASH, would give you the commits between +both the tags.
+The default behaviour of commitlog is to print to the stdout of your +terminal which might not be what you wish to do.
+So, if you wish to ever write to a file , you can use the --out FILE flag to
+write the output to a file instead.
$ commitlog g -o ./CHANGELOG.md
+++Note: commitlog will overwrite the file with the new output, make sure you +create a backup of the file when working with this.
+
++Note: In coming versions an append mode will be added to the CLI to avoid +having to deal with this manually
+
The release sub-command is a complimentary sub-command added to commitlog to
+help you with managing release versions. I understand that most languages have
+their own package version management and you might want to work with them but
+that's also why the release sub-command isn't something you need, it's there
+for cases where you might wanna use it.
My primary usecase is when working with repositories that work with multiple +languages and I'd prefer a unified version.
+The release command doesn't modify your source code files but instead handles
+the version with it's own file named .commitlog.release, which just holds the
+version number right now and while this does have the X.X.X format (semantic
+versioning format) the increments or how you handle them doesn't have to be.
The command is flexible enough for you to combine and create your own way of +versioning.
+$ commitlog release --init
+# or
+$ commitlog r --init
+Once initialized, you'll see a .commitlog.release file in your repo with the
+version v0.0.0 to start with.
Post that you can use the remaining flags to help you incrementing the version +as needed.
+$ commitlog r --major # change to v1.0.0
+$ commitlog r --minor # change to v0.1.0
+$ commitlog r --patch # change to v0.0.1
+$ commitlog r --pre # change to v0.0.0-beta.0
+$ commitlog r --pre --pre-tag="dev" # change to v0.0.0-dev.0
+
+# or go bonkers
+$ commitlog r --patch --pre --pre-tag="dev" # change to v0.0.1-dev.0
+$ commitlog r --major --patch --pre --pre-tag="dev" # change to v1.0.1-dev.0
+Most times you'd also want a tool like this to create commits and tags for you
+which is fair, so release does come with a few git actions.
--commit (will create a commit and tag it for you)--push (will push the commits and tags for you)The whole command would look a little something like this
+$ commitlog r --patch --commit --push
+These are not really hard to guess or achieve but are in the advanced section as +this isn't something a beginner user might need to mess with. If you have other +use cases that you feel like should be added here, raise a issue.
+$ commitlog g --start HEAD --end HEAD~3
+# would return the last 3 commits
+And as you might have understood, commitlog does work with git's revision system
+so you can reuse git's own revision pointers as needed. Though it's mostly
+easier to just use the HASH since, finding the hashes in git log is easier
+than finding the number you have to type after the HEAD~
In cases like these the -p or --path flag can be used with the generate
+flag
$ commitlog g -p ./sub/module -s HEAD~3
+# would return the commits from HEAD~3 to the next tag or end of all commits.
+As for why is this turned off by default? I just don't use commit standards and +mostly just need the commits between tags and very rarely need the categories to +help me but doesn't change the fact that someone else might need it.
+So, how does commitlog categorize? using regex's , or more like comma seperated +regex's.
+The implementation approach might bring some issue but I'm going to wait for +them instead of over fixing something that might never really happen.
+Anyway, a simple example for a non-scoped commitlint styled categorization would +look something like this .
+$ commitlog g --categories="feat:,fix:"
+Output:
+## feat:
+110c9b260e6de1e2be9af28b3592c373ab6fc501 feat: handling for pre increment
+
+9080580575d3579b3d11dd114830eb128f0c8130 feat: releaser base maj,min,patch setup
+
+b513e53cbbc30e5b667fbba373b9589911a47ac0 feat: generator subcommand implementation
+
+## fix:
+5bafe9d105298001707c7c816e60d3ef0257a816 fix: tag creation
+This could be made a little more neater using a better regex like so
+$ commitlog g --categories="^feat,^fix"
+Output:
+## ^feat
+e0ce9c693c554158b7b4841b799524164d9c3e83 feat(releaser): add init and pre-tag handlers
+
+110c9b260e6de1e2be9af28b3592c373ab6fc501 feat: handling for pre increment
+
+9080580575d3579b3d11dd114830eb128f0c8130 feat: releaser base maj,min,patch setup
+
+b513e53cbbc30e5b667fbba373b9589911a47ac0 feat: generator subcommand implementation
+
+## ^fix
+5bafe9d105298001707c7c816e60d3ef0257a816 fix: tag creation
+
+540bb3d7419aab314fdb999dd57eeac3c53f5fad fix doc generation
+
+87d40ddbd463ad71b3af8b7edb8ac8176ecbf2f5 fix tests for new param
+As visible, you find more commits in the 2nd one since the regex matches more +cases and gives you more information. You are free to modify these to make them +work with other patterns that you might follow.
+Also the titles are going to be the regex's you pass. A future version will add +a way for you to add label's to the regex though that's a little harder to +achieve without making the flags very verbose so I've avoided it for now.
+++Note: This is the initial implementation of this and might change in a +future major version since this flag feels a little more frictional than the +other approaches I have in mind. Feel free to recommend other ways to do this.
+
This is the entire CLI reference, which you can also access by using the -h
+flag on the downloaded binary.
commitlog -h
NAME:
+ commitlog - commits to changelogs
+
+USAGE:
+ commitlog [global options] command [command options] [arguments...]
+
+COMMANDS:
+ generate, g commits to changelogs
+ release, r manage .commitlog.release version
+ help, h Shows a list of commands or help for one command
+
+GLOBAL OPTIONS:
+ --help, -h show help (default: false)
+commitlog g -h
NAME:
+ commitlog generate - commits to changelogs
+
+USAGE:
+ commitlog generate [command options] [arguments...]
+
+OPTIONS:
+ --categories value categories to use, includes all commits by default. any text you add here will be used to create categories out of the commits
+ --end END, -e END END reference for the commit to stop including commits at.This is exclusive of the given commit reference
+ --out FILE, -o FILE path to the output FILE
+ --path PATH, -p PATH root with the '.git' folder PATH (default: ".")
+ --promo add promo text to the end of output (default: false)
+ --start START, -s START START reference for the commit to include commits from,This is inclusive of the given commit reference
+ --stdio print to the stdout (default: true)
+commitlog r -h
NAME:
+ commitlog release - manage .commitlog.release version
+
+USAGE:
+ commitlog release [command options] [arguments...]
+
+OPTIONS:
+ --commit if true will create a commit and tag, of the changed version (default: false)
+ --init initialise commitlog release (default: false)
+ --major create a major version (default: false)
+ --minor create a minor version (default: false)
+ --patch create a patch version (default: false)
+ --path PATH, -p PATH PATH to a folder where .commitlog.release exists or is to be created.(note: do not use `--commit` or `--push` if the file isn't in the root) (default: ".")
+ --pre create a pre-release version. will default to patch increment unlessspecified and not already a pre-release (default: false)
+ --pre-tag value create a pre-release version (default: "beta")
+ --push if true will create push the created release commit + tag on origin (default: false)
+