nodegit

NodeGit

Node bindings to the libgit2 project.

Linux & macOS	Windows	Coverage	Dependencies

Stable (libgit2@v0.27.3): 0.27.3

Have a problem? Come chat with us!

Visit slack.libgit2.org to sign up, then join us in #nodegit.

Maintained by

Tim Branyen @tbranyen, John Haley @johnhaley81, and Max Korp @maxkorp with help from tons of awesome contributors!

Alumni Maintainers

Steve Smith @orderedlist, Michael Robinson @codeofinterest, and Nick Kallen @nk

API Documentation.

http://www.nodegit.org/

Getting started.

NodeGit will work on most systems out-of-the-box without any native dependencies.

npm install nodegit

If you receive errors about libstdc++, which are commonly experienced when building on Travis-CI, you can fix this by upgrading to the latest libstdc++-4.9.

In Ubuntu:

sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get update
sudo apt-get install libstdc++-4.9-dev

In Travis:

addons:
  apt:
    sources:
      - ubuntu-toolchain-r-test
    packages:
      - libstdc++-4.9-dev

In CircleCI:

  dependencies:
    pre:
      - sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
      - sudo apt-get update
      - sudo apt-get install -y libstdc++-4.9-dev

If you receive errors about lifecycleScripts preinstall/install you probably miss libssl-dev In Ubuntu:

sudo apt-get install libssl-dev

You will need the following libraries installed on your linux machine:

• libpcre
• libpcreposix
• libkrb5
• libk5crypto
• libcom_err

When building locally, you will also need development packages for kerberos and pcre, so both of these utilities must be present on your machine:

• pcre-config
• krb5-config

If you are still encountering problems while installing, you should try the Building from source instructions.

API examples.

Cloning a repository and reading a file:

var Git = require("nodegit");

// Clone a given repository into the `./tmp` folder.
Git.Clone("https://github.com/nodegit/nodegit", "./tmp")
  // Look up this known commit.
  .then(function(repo) {
    // Use a known commit sha from this repository.
    return repo.getCommit("59b20b8d5c6ff8d09518454d4dd8b7b30f095ab5");
  })
  // Look up a specific file within that commit.
  .then(function(commit) {
    return commit.getEntry("README.md");
  })
  // Get the blob contents from the file.
  .then(function(entry) {
    // Patch the blob to contain a reference to the entry.
    return entry.getBlob().then(function(blob) {
      blob.entry = entry;
      return blob;
    });
  })
  // Display information about the blob.
  .then(function(blob) {
    // Show the path, sha, and filesize in bytes.
    console.log(blob.entry.path() + blob.entry.sha() + blob.rawsize() + "b");

    // Show a spacer.
    console.log(Array(72).join("=") + "\n\n");

    // Show the entire file.
    console.log(String(blob));
  })
  .catch(function(err) { console.log(err); });

Emulating git log:

var Git = require("nodegit");

// Open the repository directory.
Git.Repository.open("tmp")
  // Open the master branch.
  .then(function(repo) {
    return repo.getMasterCommit();
  })
  // Display information about commits on master.
  .then(function(firstCommitOnMaster) {
    // Create a new history event emitter.
    var history = firstCommitOnMaster.history();

    // Create a counter to only show up to 9 entries.
    var count = 0;

    // Listen for commit events from the history.
    history.on("commit", function(commit) {
      // Disregard commits past 9.
      if (++count >= 9) {
        return;
      }

      // Show the commit sha.
      console.log("commit " + commit.sha());

      // Store the author object.
      var author = commit.author();

      // Display author information.
      console.log("Author:\t" + author.name() + " <" + author.email() + ">");

      // Show the commit date.
      console.log("Date:\t" + commit.date());

      // Give some space and show the message.
      console.log("\n    " + commit.message());
    });

    // Start emitting events.
    history.start();
  });

For more examples, check the examples/ folder.

Unit tests.

You will need to build locally before running the tests. See above.

npm test

Changelog

<a name="v0-25-0-alpha-13" href="#v0-25-0-alpha-13">v0.25.0-alpha.13</a> (2019-06-26)

Full Changelog

Summary of changes

• Turn on GIT_USE_NSEC on all platforms
• Use Iconv on OSX for better internationalization support.
• Bump libgit2 to bring in:
  • NTLM proxy support
  • Negotiate/Kerberos proxy support
  • Various git config fixes
  • Various git ignore fixes
  • Various libgit2 performance improvements
  • Windows/Linux now use PCRE for regex, OSX uses regcomp_l, this should address collation issues in diffing
• Fixed bug with Repository.prototype.refreshReferences dying on corrupted reference. We now ignore corrupted references

Merged PRs into NodeGit

• refresh_references.cc: skip refs that can't be directly resolved #1689
• Bump libgit2 to fork of latest master #1690

Merged PRs into LibGit2

• errors: use lowercase
• largefile tests: only write 2GB on 32-bit platforms
• Fix broken link in README
• net: remove unused git_headlist_cb
• cmake: default NTLM client to off if no HTTPS support
• attr: rename constants and macros for consistency
• Change API instances of fromnoun to from_noun (with an underscore)
• object: rename git_object__size to git_object_size
• Replace fnmatch with wildmatch
• Documentation fixes
• Removal of p_fallocate
• Modularize our TLS & hash detection
• tests: merge::analysis: use test variants to avoid duplicated test suites
• Rename options initialization functions
• deps: ntlmclient: disable implicit fallthrough warnings
• gitignore with escapes
• Handle URLs with a colon after host but no port
• Merge analysis support for bare repos
• Add memleak check docs
• Data-driven tests
• sha1dc: update to fix endianess issues on AIX/HP-UX
• Add NTLM support for HTTP(s) servers and proxies
• Callback type names should be suffixed with _cb
• tests: checkout: fix symlink.git being created outside of sandbox
• ignore: handle escaped trailing whitespace
• Ignore: only treat one leading slash as a root identifier
• online tests: use gitlab for auth failures
• Ignore files: don't ignore whitespace
• cache: fix cache eviction using deallocated key
• SECURITY.md: split out security-relevant bits from readme
• Restore NetBSD support
• repository: fix garbage return value
• cmake: disable fallthrough warnings for PCRE
• Configuration parsing: validate section headers with quotes
• Loosen restriction on wildcard "*" refspecs
• Use PCRE for our fallback regex engine when regcomp_l is unavailable
• Remote URL last-chance resolution
• Skip UTF8 BOM in ignore files
• We've already added ZLIB_LIBRARIES to LIBGIT2_LIBS so don't also add the z library
• Define SYMBOLIC_LINK_FLAG_DIRECTORY if required
• Support symlinks for directories in win32
• rebase: orig_head and onto accessors
• cmake: correctly detect if system provides regcomp
• Correctly write to missing locked global config
• [RFC] util: introduce GIT_DOWNCAST macro
• examples: implement SSH authentication
• git_repository_init: stop traversing at windows root
• config_file: check result of git_array_alloc
• patch_parse.c: Handle CRLF in parse_header_start
• fix typo
• sha1: don't inline git_hash_global_init for win32
• ignore: treat paths with trailing "/" as directories
• Test that largefiles can be read through the tree API
• Tests for symlinked user config
• patch_parse: fix parsing addition/deletion of file with space
• Optimize string comparisons
• Negation of subdir ignore causes other subdirs to be unignored
• xdiff: fix typo
• docs: clarify relation of safe and forced checkout strategy
• Each hash implementation should define git_hash_global_init
• [Doc] Update URL to git2-rs
• remote: Rename git_remote_completion_type to _t
• odb: provide a free function for custom backends
• Have git_branch_lookup accept GIT_BRANCH_ALL
• Rename git_transfer_progress to git_indexer_progress
• High-level map APIs
• refdb_fs: fix loose/packed refs lookup racing with repacks
• Allocator restructuring
• cache: fix misnaming of git_cache_free
• examples: produce single cgit2 binary
• Remove public 'inttypes.h' header
• Prevent reading out of bounds memory
• Fix a memory leak in odb_otype_fast()
• Make stdalloc__reallocarray call stdalloc__realloc
• Remove git_time_monotonic
• Fix a very improbable memory leak in git_odb_new()
• ci: publish documentation on merge
• Enable creation of worktree from bare repo's default branch
• Allow bypassing check for '.keep' file
• Release v0.28.1