node-git-wip

git-wip implementation entirely in node.

Targeted for use alongside other git [gui] tools and use with automatic deployment scripts.

How this git-wip works

When called, this git-wip will create a new commit on a branch with the name wip/$branch, creating it if required. It also leaves the index in the same state as the latest wip commit, with everything staged. Once complete, git-wip will report the hash and/or the WIP branch name of the new commit. This is targeted at usage by other automatic testing systems.

When subsequent calls to git-wip are made, it simply continues the previously created branch.

By default, this git-wip will mark the current head as a parent if the latest wip.

Install

$ yarn add @cinderblock/node-git-wip --dev

My use cases are usually only needed on development machines and I preffer not to install packages globally. All the features should work just fine if installed globally.

Usage

Module

const wip = require('@cinderblock/node-git-wip');

wip({
    historyStrategy: 'manual',
    // ...
});

cli

$ git-wip

There are currently no command line options. To control features, use a configuration file.

Options

There are a couple options that more dramatically change the behavior than others.

• historyStrategy
• message
• pathspec
• prefix
• repo

All options are passed as an object to the exported function. Options are also loaded from any configuration file according to cosmiconfig's search pattern. Options from config files are merged with options passed to the function with the latter taking precedence.

All options

Any option left undefined will default to something sensible.

author

Author of wip commit.

Default: Default author from repository

ceilingDirs

How high up the directory tree should we search for a .git folder indicating a repository?

Default: ''

committer

Committer of wip commit.

Default: author

debug

Control where debug data is sent.

Default: false

• false-ish or 'off' disables logging.
• true-ish logs to stdout.
• 'stderr' will send to stderr.
• A function can also be passed.

debugSteps

Extra debugging information.

Default: undefined

discoverAcrossFs

When searching parent directories for which git repository to open, controls if we stop when we cross a filesystem boundary.

Default: false

flags

Controls the git flags when adding files to the index before committing.

Default: none

• An integer number from 0-7 where each bit corresponds to a flag
• An object with properties controlling the flags and the following shape:

  {
    force: false,
    disablePathspecMatch: false,
    checkPathspec: false,
  }

historyStrategy

Controls how history will look

Default: 'merge'

• 'merge' marks HEAD branch as a parent of current branch
• 'parallel' or 'manual' does not connect the wip branch to the HEAD branch past the first commit
• 'clear' or 'reset' creates a new branch when HEAD branch has moved forward

message

Controls the commit message

Default: 'WIP'

pathspec

Controls which files are added to the WIP commit.

Default: ['*'] This option is an array of git pathspec strings.

postfix

Use a postfix string instead of a prefix.

Default: undefined If defined, prefix option is ignored.

prefix

Controls the prefix added to the current HEAD branch name.

Default: 'wip'

• Any sensible non-empty string of valid git branch name characters can be used
• A function that takes in the name of the current HEAD branch (ie 'master') and returns the new branch name.

repo

If you already have an instance of NodeGit.Repository open, pass it in to reuse it.

Default: undefined

If repo is defined and the correct type, repoPath and related options are ignored.

repoPath

Controls where we start looking for the git repository.

Default: '.'

separator

Controls the separator used when constructing the wip branch name from the HEAD branch name.

Default: '/'

useNestedPrefix

Controls if, when using branches in "folders", to put all the different wip branches together in one directory at the top level, or to put them near each branch.

For instance, if you are working on a branch called feature/foobar:

• true creates a branch feature/wip/foobar
• false creates a branch wip/feature/foobar

Default: true