+TITLE: git-notary +SUBTITLE: a versioning experiment for git +LATEX: pagebreak

~git-notary~ generates canonical version tags from versioning notes.

** Why would I want this?

~git-notary~ may be helpful if you want to use Semantic Versioning in a project with many contributors and some manner of branch-oriented workflow. Tracking versioning information with a ~VERSION~ file seems like a great idea, but has some quirks.

** An Example Scenario

Consider the following (simplified) scenario:

+BEGIN_EXAMPLE

,*   e44e210 - (HEAD -> develop) Merge branch 'bar' into develop
|\
| * e1793f3 - (bar) PATCH
| * f231d3b - MAJOR 
| * 5c69653 - MAJOR
,* |   67543e1 - Merge branch 'foo' into develop
|\ \
| |/
|/|
| * ea81623 - (foo) MAJOR
| * 8b773db - PATCH
| * 6613b79 - MINOR
|/
,* 21c36f3 - (master) MINOR
,* 64357c2 - MINOR
,* 9ebfd7d - MINOR
,* cc5d832 - PATCH
,* ebc851f - MINOR
,* a75790f - PATCH
,* 572a9e8 - MAJOR
,* a990127 - (tag: 0.0.0) INITIAL

+END_EXAMPLE

In this example, two branches (~foo~ and ~bar~) were created from ~master~ (~21c36f3~). Both branches know that ~1.4.0~ is the latest tag (at the time they branched). Let's assume these branches do not conflict with each other.

With a ~VERSION~ file, a project generally chooses one of two places to update it:

If ~foo~ merges first, the expected version post-merge is ~2.0.0~.

If ~bar~ merges first, the expected version is ~3.0.1~.

At ~e44e210~ (~HEAD~ of ~develop~), the final version should be ~4.0.1~, but if the merge order were reversed, it should be ~4.0.0~. This gets worse as the number of active branches increases.

** Install via RubyGems

#+BEGIN_SRC shell
  gem install git-notary
#+END_SRC

** Manual Installation

Download the latest release of ~git-notary~ and place it somewhere in your ~$PATH~.

+LATEX: pagebreak

** Add new versioning information

+BEGIN_SRC shell

git-notary new <version> [object] [namespace]

+END_SRC

Where <version> is one of (major, minor, patch).

** Undo a version

+BEGIN_SRC shell

git-notary undo [object] [namespace]

+END_SRC

** Fetch versioning notes

+BEGIN_SRC shell

git-notary fetch [remote] [namespace]

+END_SRC

** Fetch and merge versioning notes

+BEGIN_SRC shell

git-notary pull [remote] [namespace] [merge-strategy]

+END_SRC

** Push versioning notes

+BEGIN_SRC shell

git-notary push [remote] [namespace]

+END_SRC

** Extract Notes

+BEGIN_SRC shell

git-notary notes [branch] [base] [namespace]

+END_SRC

** Compute Versions from Notes

+BEGIN_SRC shell

git-notary notes | git-notary versions [initial]

+END_SRC

** Generate Tags from Versions

+BEGIN_SRC shell

git-notary notes | git-notary versions | git-notary tags [--apply]

+END_SRC

~git-notary~ is available under the [[tldrlegal.com/license/mit-license][MIT License]]. See ~LICENSE.txt~ for the full text.