From 36d09c0367ee464eda61a5d4fed2d4c957d5b5e5 Mon Sep 17 00:00:00 2001
From: "D. Moonfire" <d.moonfire@moonfire.us>
Date: Mon, 11 Mar 2024 08:45:15 -0500
Subject: [PATCH] docs: added a read me file

---
 README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..34598b2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,84 @@
+# MfGames Conventional Commit
+
+_A small utility that calculates the sematic version from conventional commits in a Git repository._
+
+This utility does one thing only, calculate the [semantic version]() from Git commits that conform to the [conventional commit]() specification. It is path-aware which means only commits inside certain directories are included in the calculation. The current version number is built from the highest sematic version tag found in the commit's parents.
+
+For example, the version of "Package1" will be 1.2.4 and "Package2" will be 1.3.0 from the following commits:
+
+- fix: fixing package1
+  - src/package1/file1.txt
+- feat: fixing package2
+  - src/package2/file2.txt
+- fix: sweeping change
+  - src/package1/file.txt
+  - src/package2/file.txt
+- feat: current version [tagged "Package1-1.2.3", "Package2-1.2.3"]
+  - src/package1/file.txt
+  - src/package2/file.txt
+
+In the above example, the second commit is ignored while calculating the "Package1" commits while the first one is ignored while calculating "Package2".
+
+If a version cannot be found, this will use `0.0.1`.
+
+## Configuration
+
+Configuration is done via a file checked into the Git root in `.config/mfgames-conventional-commit.json`. An example file is below:
+
+```json
+{
+  "$schema": "https://mfgames.com/mfgames-conventional-commit/schemas/v0.0.json",
+  "packages": {
+    "Package1": {
+      "tag_prefix": "Package1-*",
+      "paths": { "include": ["src/package1/**/*"] }
+    },
+    "Package2": {
+      "tag_prefix": "Package2-*",
+      "paths": { "include": ["src/package2/**/*"] }
+    }
+  }
+}
+```
+
+To use this in a single package repository, the following can be used:
+
+```json
+{
+  "$schema": "https://mfgames.com/mfgames-conventional-commit/schemas/v0.0.json",
+  "packages": {
+    "default": {
+      "tag_prefix": "v*",
+      "paths": { "include": ["**/*"] }
+    }
+  }
+}
+```
+
+At the moment, configuration has poor error handling, so if the program says it cannot read the configuration file, check the file. The schema will change "soon".
+
+## Usage
+
+The executable is `mfgames-conventional-commit`.
+
+```shell
+mfgames-conventional-commit --package Package1
+```
+
+### Options
+
+#### `--directory PATH`
+
+The directory (or sub-directory) inside the Git repository. If this is not provided, then the current working directory will be used.
+
+#### `--package NAME`
+
+_Required_
+
+The name of the package, case-sensitive, that matches the package name inside the configuration. This can be used anywhere within the Git repository, not just within the directories for that project.
+
+_In the future, this will not be required if run inside a directory that only exists inside a single project._
+
+#### `-v`, `--verbose`
+
+Increase the level of verbosity. At default, this will only show warnings and errors on stderr and write out the calculated version on stdout. When this option is given (three levels), it will write out increasingly more information about how the version is calculated.