Gitsome

A small library which helps make decisions based on the existing data in a git repository. It's easy to extract the 'next' version number based on the keywords you provide. It's also simple to do more complex and interesting things given the exposed arrays of commits.

Motivation

I want to have a reliable way of making decisions about versioning projects to remove some of the risk for errors.

Installation

If you want to skip devDependencies, add the '--production' flag to your install command:

$ npm install gitsome --save --production

Code Example

Given this initialization...

const gitSome = require('gitsome')

const options = {
  path: '/Set/to/a/local/git/repo',
  tag: true
}

const gs = gitSome(options)

gs.version() can be used like this:

const keywords = {
  minor: ['merge', 'feature'],
  patch: ['patch', 'fix', 'refactor', 'tweak', 'update']
}

const { current, diff, next } = gs.version(keywords)
// current => 1.0.0 (last tag, or defaults to 1.0.0)
// diff => 0.0.1
// next => 1.0.27

// A diff of 0.1.0 is applied like this
const { current, diff, next } = gs.version(keywords, '0.2.3') // notice also this forced current-version
// current => 0.2.3
// diff => 0.1.0
// next => 0.3.0

gs.version(keywords) Matches commits against the keywords, resulting in a semver 'next' value. several other properties are also returned for the sake of flexibility:

current defaults to: last known tagged version OR 1.0.0 if none is found

diff is the number of commits counted from version.current to now, aggregated down into an incremental format.

next is version.current + version.diff

commits is a copy of the commits which make up the version bump, separated into 'minors' and 'patches'.

gs.Commits is an array of 'commit' objects. It's elements can be fully customized by passing an array of 'git-log format:' formatters into the gitsome options object. By default, it will include every available formatter.

Commit object (example from vuejs/vue)

{
  "commitHash": "b8f730ce989a176437dd3a3c359a469c121e10a7",
  "commitHashShort": "b8f730c",
  "treeHash": "60bae6133e7a2d879a4d34ec94c211cf2ab4d60e",
  "treeHashShort": "60bae61",
  "parentHashes": "c289a7e240e6a0fa22c0fda8bc3ecb1835455acd",
  "parentHashesShort": "c289a7e",
  "authorName": "Anirudh Sanjeev",
  "authorEmail": "[email protected]",
  "authorDate": "Fri Jul 22 22:49:31 2016 +0530",
  "authorDateFull": "Fri, 22 Jul 2016 22:49:31 +0530",
  "authorDateRelative": "3 weeks ago",
  "authorDateTimestamp": "1469207971",
  "authorDateISO": "2016-07-22 22:49:31 +0530",
  "authorDateISOStrict": "2016-07-22T22:49:31+05:30",
  "committerName": "Evan You",
  "committerEmail": "[email protected]",
  "committerDate": "Fri Jul 22 13:19:31 2016 -0400",
  "committerDateFull": "Fri, 22 Jul 2016 13:19:31 -0400",
  "committerDateRelative": "3 weeks ago",
  "committerDateTimestamp": "1469207971",
  "committerDateISO": "2016-07-22 13:19:31 -0400",
  "committerDateISOStrict": "2016-07-22T13:19:31-04:00",
  "refNames": "HEAD -> dev, origin/dev, origin/HEAD",
  "encoding": "",
  "subject": "Handle back-ticks in expression (#3292)",
  "subjectDashed": "Handle-back-ticks-in-expression-3292",
  "body": [
    "Handle back-ticks in expression (#3292)"
  ],
  "commitNotes": "",
  "reflogSector": "",
  "reflogIdentityName": "",
  "reflogIdentityEmail": "",
  "reflogSubject": ""
}

Future

Complete the test suite. Implement new methods to do fun things with the gitsome.commits array. Further explore the application of functional paradigms on the codebase.

License

MIT. See LICENSE in this repo.