git-notary generates canonical version tags from versioning notes.
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.
Consider the following (simplified) scenario:
* 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
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.
- Versioning is important.
- Versions should communicate scope of change.
- Humans can signal the scope of their own changes.
- Machines can figure out the rest.
gem install git-notaryDownload the latest release of git-notary and place it somewhere in your $PATH.
git-notary new <version> [object] [namespace]Where <version> is one of (major, minor, patch).
git-notary undo [object] [namespace]git-notary fetch [remote] [namespace]git-notary pull [remote] [namespace] [merge-strategy]git-notary push [remote] [namespace]git-notary notes [branch] [base] [namespace]git-notary notes | git-notary versions [initial]git-notary notes | git-notary versions | git-notary tags [--apply]git-notary is available under the MIT License. See LICENSE.txt for the full text.