Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

git-clone-or-pull

strugee34LGPL-3.0+4.0.0

Ensure a git repo exists on disk and that it's up-to-date

git, clone, pull

readme

git-clone-or-pull

Build Status Coverage Status npm Greenkeeper badge

Ensure a git repo exists on disk and that it's up-to-date

Installation

npm install git-clone-or-pull

Node 4.x or greater is required. The module will probably work on Node 0.12, but the tests do not. So I wouldn't count on it.

Usage

Simple example:

var cloneOrPull = require('git-clone-or-pull');
var path = require('path');

cloneOrPull('git://github.com/strugee/node-git-clone-or-pull.git', path.join(process.cwd(), 'node-git-clone-or-pull'), function(err) {
    if (err) throw err;

    // Use repo
});

The cloneOrPull() function takes three arguments. In order:

url (String) - the URL to clone from

opts (String or Object) the pathname to clone to if a String, otherwise an object containing module options (see "Options" below)

callback (Function) function callback that will be called upon completion of the clone or pull. If there is an error, it will be passed as the first argument.

Options

path (String) - the pathname to clone to. If a String is provided instead of an options Object, it will be used as path's value.

implementation (String) - the implementation to use; defaults to nodegit in most cases (see "Implementations" below)

branch (String) - the branch to use; defaults to master (even if the default upstream branch is something else)

Implementations

  • nodegit uses NodeGit, the libgit2 bindings for Node.
  • subprocess is based on spawning git subprocesses (which means you need a git binary installed).

Implementation is determined with the following algorithm:

  1. If opts.implementation exists its value will be used as the implementation; if that implementation is unavailable an error will be returned to the callback
  2. If NodeGit can be loaded, the implementation will be nodegit
  3. If git --version returns an exit code of 0, the implementation will be subprocess
  4. No implementation can be found and an error will be returned to the callback

Each implementation has its negatives: nodegit makes installation slightly more complicated. subprocess works on most systems - but it requires an external binary.

License

LGPL 3.0+

Author

AJ Jordan alex@strugee.net

changelog

git-clone-or-pull changelog

git-clone-or-pull follows Semantic Versioning.

4.0.0 - 2020-02-10

Added

  • Support Node 10 and Node 12

Breaking

  • Drop Node 4, Node 6, and Node 7

Security

  • Pull in a newer NodeGit to fix some (pretty old) security vulnerabilities

3.1.1 - 2017-11-15

Fixed

  • JSHint is now marked as a development dependency, not a production dependency (#22)

3.1.0 - 2017-09-17

Improved

3.0.0 - 2017-08-10

Improved

Breaking

  • Drop support for Node 5 due to NodeGit doing the same
  • Stop pretending we support Node 8 when NodeGit upstream doesn't support Node 8

2.2.0 - 2017-04-03

Improved

  • Support specifying which branch to use

2.1.0 - 2016-11-09

Changed

  • Upgrade to smart-spawn@2

2.0.1 - 2016-10-29

Fixed

  • The NodeGit implementation now properly passes clone errors to the callback

2.0.0 - 2016-10-29

Breaking

  • Node 0.10 support has been dropped
  • Pulling no longer double-checks that the on-disk origin remote URL matches the provided URL

1.1.2 - 2016-09-07

Fixed

  • Support Node 0.10 by not using require('child_process').spawnSync

1.1.1 - 2016-09-07

Fixed

  • Actually mark NodeGit as optional in package.json

1.1.0 - 2016-09-06

Added

  • New git subprocess-based implementation which is used automatically if NodeGit can't be loaded

Changed

  • NodeGit is now an optional dependency
  • Advanced options can be specified by passing an object instead of a pathname

Fixed

  • The passed callback is now called by the NodeGit implementation if the repo hasn't been cloned yet

1.0.0 - 2016-07-14

Added

  • Initial release