doc: update examples and pre-release format

1 files changed, 61 insertions, 15 deletions

diff --git a/README.md b/README.md
index dfe2e9b..c633c31 100644
--- a/README.md
+++ b/README.md
@@ -2,53 +2,59 @@
 
 _Inspired by the python bump2version tool._
 
-bumpver - next semantec version in a given sequence
+bumpver - print the next semantec version in a given sequence
 
 ## Usage
 
 ```bash
-bumpver part [major|minor|patch] file [-|file] [flags]
+bumpver part [major|minor|patch] [flags] file [-|file] 
 ```
 
 ## Why?
 
-- Most version bumpers are fairly tightly coupled to git.
-- Most like to make commits for you
-- Few seem to have useful pre release mechanisms
-- None seem to provide simple interfaces
+- Most version bumpers are fairly tightly coupled to git
+- Make commits for you
+- Few have useful pre release mechanisms
+- Lack of simple interfaces
 - Lack of unix philosophy
 
-Many tools touch git and some opinionatedly like to touch it.
-
 ## How?
 
 `go-bumpver` takes the sequence of version(s) from a file or stdin and prints the next version. It drops invalid versions in the sequence and only uses valid ones. It does not make a tag or change any state in git or any other VCS it only prints the next version.
 
+`go-bumpver` has simple but ability to bump pre-release tags using simple formating string.
+
 ### Inputs
 
 **stdin**
 ```bash
 ❯ echo "1.1.1\n1.2.1" | bumpver patch -
-1.2.2%
+1.2.2
 ```
 
 **file**
 ```bash
 ❯ echo v0.1.0 > VERSION
 ❯ bumpver patch VERSION
-0.1.1%
+0.1.1
 ```
 
 **local repo**
 ```bash
 ❯ bumpver patch <(git tag -l)
-3.3.2%
+3.3.2
 ```
 
 **remote repo**
 ```bash
 ❯ bumpver patch <(git ls-remote --tags --refs origin v\* | awk -F'[ /]' '{ print $NF }')
-3.3.4%
+3.3.4
+```
+
+**bump tags released on a branch**
+```bash
+❯ bumpver patch <(git tag --merged <release branch name>)
+2.1.4
 ```
 
 ### Bumps
@@ -56,17 +62,57 @@ Many tools touch git and some opinionatedly like to touch it.
 **a patch**
 ```bash
 ❯ bumpver patch <(git tag -l)
-3.3.2%
+3.3.2
 ```
 
 **a minor**
 ```bash
 ❯ bumpver minor <(git tag -l)
-3.4.0%
+3.4.0
 ```
 
 **a major**
 ```bash
 ❯ bumpver major <(git tag -l)
-4.0.0%
+4.0.0
+```
+
+### Pre-release
+
+Pre-releases can be formatted in a way that can be easily bumped. Providing `--prerelease` will generate a new prerelease for the given bump. Meaning if you use `major --prerelease` with the last version 1.2.2 will give `2.0.0-RC.0`.
+
+Use Case:
+- A Pull Request/Merge Request is opened. A tag needs to be generated for the PR/MR.
+- Bumping release candidates for testing.
+
+#### Format Strings
+
+- `$BumpInt`: increases the integer value.
+- `$KeyArg <KEY NAME>`: Value of the key from `key-args` option
+
+#### $BumpInit
+
+Consider the following format string: `rc.$BumpInt`
+
+```bash
+❯ echo "0.1.0-rc.1" | bumpver patch --prerelease --prerelease-fmt 'rc.$BumpInt' -
+0.1.0-rc.2
+```
+
+A none existant pre-release yields
+
+```bash
+❯ echo "0.1.0" | bumpver patch --prerelease --prerelease-fmt 'rc.$BumpInt' -
+0.1.1-rc.0
+```
+
+#### $KeyArg
+
+`$KeyArg` allows for run time side effects on prerelease versions. This means you can bump ain integer or provide key word argument. Examples:
+- add the PR/MR number to the version
+- add metadata for the version
+
+```bash
+❯ bumpver patch --prerelease --prerelease-fmt 'rc.$KeyArg PR_NUM.$BumpInt' --key-args PR_NUM=44 vers.txt
+1.2.2-rc.44.0
 ```