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

* Overview

~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:

- Updates occur in the branch. In this case, once either branch is merged, the
  other is in conflict with it.
- Updates occur in the trunk. In this case, the trunk now contains code that did
  not originate in a branch. Again, the first merged is safe, but the other is
  in a conflicting state.

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.

* Assumptions

- Versioning is important.
- Versions should communicate scope of change.
- Humans can signal the scope of their own changes.
- Machines can figure out the rest.

* Installation

** Install via RubyGems

~gem install --no-wrapper git-notary~

** Manual Installation

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

#+LATEX: \pagebreak

* Usage

** 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

** 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

* License

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

* Contributors
- [[https://colstrom.github.io/][Chris Olstrom]] | [[mailto:chris@olstrom.com][e-mail]] | [[https://twitter.com/ChrisOlstrom][Twitter]]