From b8a7a0e66e1f67c366a1f1eac9e3024b59f20fdd Mon Sep 17 00:00:00 2001
From: Michael Juarez <mike@imgix.com>
Date: Mon, 7 Dec 2020 18:10:45 -0800
Subject: [PATCH] First pass at more relevant docs

---
 README.md | 75 ++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 60 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index c5122df..2d6f881 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,7 @@ avakas
 
 [![PyPI](https://img.shields.io/pypi/v/avakas.svg)](https://pypi.python.org/pypi/avakas)[![Maintenance](https://img.shields.io/maintenance/yes/2020.svg)]()
 
+
 # Overview
 
 This script provides a simple interface around viewing and manipulating project version metadata. It may be used to either bump, set, or view the version information for the project in a given directory. It is written with [semantic versioning](http://semver.org/) in mind.
@@ -12,24 +13,21 @@ It currently does it's best to determine whether the given directory contains a
 The avakas tool makes a few assumptions
 
 * There is only one logical project in each directory.
-* The directory is somewhere in a git repository. You can have multiple projects per repository by using the `--tag-prefix` option.
-* For the protection of the user the git workspace must not be dirty.
 
 The avakas tool supports the following types of version files
 
 * NodeJS `package.json`
 * Erlang/OTP and rebar `foo.app.src`
 * Chef Cookbook `metadata.rb`
+* Ansible `meta/main.yml`
 * Plain ol' `version` file
 
+
 # Operations
 
 ## show
 
-This mode will return the current version for a given project. The following will show the current Public API version. This operation supports an additional `--build` argument, which will cause it to extend the version set in source control with build-time metadata. It also supports the `--pre-build` argument, which does the same thing on top of the prerelease field, because all kinds of package management systems do not actually support the build semantic version component.
-
-It is possible to override this default `pre-build` behavior. The `--pre-build-date` option will include the current date (down to the second) as a string. The `--pre-build-prefix=foo` option will include a string prefix. It is possible to include both pre-build _and_ build information, but only if you specify a prefix or include the date in prebuild.
-
+This mode will return the current version for a given project. Some optional arguments include:
 
 ```shell
 avakas show $HOME/projects/hal9000
@@ -38,6 +36,7 @@ avakas show $HOME/projects/hal9000
 ## set
 
 This mode will set an explicit version. Note that the string must be a valid semantic version.
+
 ```shell
 avakas set $HOME/projects/hal9000 2.0.0
 ```
@@ -56,7 +55,7 @@ This mode will automatically update the version based on the input provided. It
 
 When the `auto` option is selected, the system will use hints in the git log since the last version bump to determine if the version should be changed. These hints can be specified at any point in the commit message. The hints are specified, prefixed by `bump:`. For example, the following commit message would result in a minor version bump if it is subsequently "autobumped".
 
-```
+```shell
 $ avakas show .
 0.0.1
 $ git commit -am "hello this is a release\nbump:minor"
@@ -64,23 +63,67 @@ $ avakas bump . auto
 Version updated from 0.0.1 to 0.1.0
 ```
 
+Avakas can also rely on a default bump version to ensure every invocation of Avakas generates a bump build. If a bump hint is not detected within the commit history, the defined defualt-bump level will be used. This is useful for CI/CD systems.
+
+```shell
+avakas bump . auto --default-bump patch
+```
+
+
 # Arguments
 
-### `--dry-run`
+## --tag-prefix
+
+A prefix to use with the version. Generally used for non-semantic version compliant v1.0 style version strings.
+
+## --branch
+
+The authoritative mainline branch of your project. This is also used to compare for prereleases.
+
+## --remote
+
+The git remote origin to push changes to.
 
-This will result in nothing being pushed to upstream git sources.
+## --filename
 
-### `--branch`
+The filename to use for generating a version file.
 
-The branch to use when updating git.
+## --flavor
 
-### `--remote`
+Flavor of project (Presently: legacy|chef|ansible|nodejs|erlang).
 
-The remote to push tags and version updates.
+## --build-meta
 
-### `--tag-prefix`
+Whether to apply semantic version compliant build metadata to the version. (Example: `1.0.0+4c5fa2.1`)
+
+## --skip-dirty
+
+Skip checking if local repo is dirty.
+
+## --skip-commit-changes
+
+Skip committing generated version files.
+
+## --with-hooks
+
+Run git hooks during operations.
+
+## --dry-run
+
+Will not push to git.
+
+## --prerelease
+
+Will attempt to generate a prerelease version. (Example: `1.0.0-1`)
+
+## --prerelease-date
+
+Will attach the data to the prerelease identifiers. (Example: `1.0.0-1.20201220`)
+
+## --prerelease-prefix
+
+Will use a prefix for the prerelease. (Example: `1.0.0-alpha.1`)
 
-This prefix will be added to the version string when creating a git tag.
 
 # Docker
 
@@ -102,10 +145,12 @@ $ cp ~/.ssh/id_rsa /tmp/ssh-avakas-working
 $ docker run  -v $(pwd):/app -v /tmp/ssh-avakas-working:/etc/avakas otakup0pe/avakas set /app 0.0.1
 ```
 
+
 # License
 
 [MIT](https://github.com/otakup0pe/avakas/blob/master/LICENSE)
 
+
 # Author
 
 The avakas tool was created by [Jonathan Freedman](http://jonathanfreedman.bio/).