Wrap node.js' fs module and expose the contents of git repositories
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



An fs-compatible module compatible that exposes the contents of git repositories (including bare ones) inside virtual gitFakeFs folders.

var FsPlusGit = require('fsplusgit'),
    fsPlusGit = new FsPlusGit(require('fs'));

fsPlusGit.readFile('/path/to/repo.git/gitFakeFs/HEAD/fileAtTheRootOfTheRepo.txt', 'utf-8', function (err, contents) {/*...*/});
fsPlusGit.readFile('/path/to/repo.git/gitFakeFs/index/fileAtTheRootOfTheRepo.txt', 'utf-8', function (err, stagedContents) {/*...*/});
fsPlusGit.readdir('/path/to/repo.git/gitFakeFs/branches/', function (err, branchNames) {/*...*/});
fsPlusGit.readdir('/path/to/repo.git/gitFakeFs/tags/', function (err, tagNames) {/*...*/});
fsPlusGit.readdir('/path/to/repo.git/gitFakeFs/tags/foo/', function (err, fileNamesAtTheRootInFoo) {/*...*/});

All other method calls are proxied to the wrapped fs module, so any operation happening outside the gitFakeFs folders should work as usual.

There's also a special folder containing all the files and directories that have staged changes. This is useful in a pre-commit hook scenario where you might want to only lint the files that actually have changes:

fsPlusGit.readdir('/path/to/repo.git/gitFakeFs/changesInIndex/', function (err, entriesWithChangesInIndex) {/*...*/});
fsPlusGit.readFile('/path/to/repo.git/gitFakeFs/changesInIndex/fileWithStagedChanges.txt', 'utf-8', function (err, stagedContents) {/*...*/});

The indexOrWorkingCopy folder has the contents of the index shadowed by the untracked files in the working copy.

You can also patch the fs module in-place to make every other module instantly capable of getting to the contents of your git repositories. Just make sure to do it before any other module might grab a reference to an fs method:


require('glob')('**/*', {cwd: '/path/to/repo.git/gitFakeFs/', mark: true}, function (err, fileNames) {
    if (err) throw err;

which will produce something like:

[ 'HEAD/',


The synchronous fs operations aren't supported inside the gitFakeFs folders due to limitations in the underlying libraries. If you need to make this work (eg. with third party code that uses readFileSync, such as the less compiler), you can wrap FsPlusGit in a cachedfs and make sure that you have read the files that you need to access before passing on control to the code that needs the synchronous operations to work:

var fs = require('fs'),
    glob = require('glob'),
    async = require('async');

glob('/path/to/repo.git/gitFakeFs/HEAD/**/*.less', {stat: true}, function (err, lessFileNamesInHead) {
    if (err) throw err;
    async.each(lessFileNamesInHead, fs.readFile, function (err) {
        if (err) throw err;
        // Now it's safe to require('fs').readFileSync() and .stat() any .less file in repo.git/gitFakeFs/HEAD/

        require('less').render(fs.readFileSync(lessFileNamesInHead[0], 'utf-8'), function (err, cssText) {
            // ...


Uses gitfakefs, which in turn uses nodegit to do the actual reading from git repositories.


Make sure you have node.js and npm installed, then run:

npm install fsplusgit


3-clause BSD license -- see the LICENSE file for details.