Node.js Adapter for js-git File System Access

1.0.0 · abandoned · verified Sun Apr 19

git-node-fs is a Node.js adapter designed to provide file system access for the deprecated `js-git` library. It enables `js-git` to interact with Git repositories directly on the local filesystem. The package's latest version, 1.0.0, was published over 10 years ago, indicating it is no longer actively maintained. Its core dependency, `js-git`, also appears to be unmaintained, making `git-node-fs` unsuitable for new projects or environments requiring modern Git features or security updates. Developers seeking current Git integration in Node.js should explore actively maintained alternatives such as `isomorphic-git` or `simple-git` which offer broader platform support (including browsers) and modern JavaScript features like Promises and ESM. The package provides a CommonJS interface for mixing file system capabilities into a `js-git` repository object.

Common errors

```
TypeError: require is not a function
```
cause Attempting to use `require()` in an ES module context, or using `import` for a CommonJS-only package.

fix If in an ES module, use dynamic `import()` or switch to a CommonJS file (e.g., rename to `.cjs` or set `"type": "commonjs"` in `package.json`). This package does not provide ESM exports.
```
Error: Cannot find module 'js-git/mixins/fs-db'
```
cause The `js-git` package, or its specific mixin, is not installed or incorrectly resolved.

fix Ensure `js-git` is installed: `npm install js-git`. Verify the module path in your `require()` statement is correct.

Warnings

breaking The package is CommonJS-only and does not support ES Modules. Attempting to `import` it will result in a runtime error.
Fix: Ensure your project is configured for CommonJS (`package.json` `"type": "commonjs"`) or use `require()` syntax within an ES module context by employing dynamic import or a transpilation step.
breaking This package, and its core dependency `js-git`, are largely unmaintained and have not seen updates in over a decade. They are not compatible with modern Git features, Node.js versions, or best practices, and may contain unpatched security vulnerabilities.
Fix: Avoid using `git-node-fs` for new projects. Migrate existing projects to actively maintained Git libraries for Node.js such as `isomorphic-git` or `simple-git`.
gotcha No TypeScript type definitions (`.d.ts` files) are provided or available for `git-node-fs` or `js-git`. Usage in TypeScript projects will require manual type declarations or casting to `any`.
Fix: If using TypeScript, you will need to create custom declaration files (`.d.ts`) or use `@ts-ignore` to suppress type errors.
gotcha The `fs` argument in `require('js-git/mixins/fs-db')(repo, fs)` refers to Node.js's built-in `fs` module, not an npm package with the same name. There are npm packages named `fs` (e.g., `fs@0.0.1-security`, `node-fs`) that are security placeholders or deprecated modules.
Fix: Always explicitly import Node.js built-in modules using the `node:` prefix (e.g., `require('node:fs')`) to prevent accidentally importing an unrelated npm package.

Install

npm install git-node-fs npm
yarn add git-node-fs yarn
pnpm add git-node-fs pnpm

Imports

git-node-fs
wrong:
```
import fsAdapter from 'git-node-fs';
```
correct:
```
const fsAdapter = require('git-node-fs');
```
This package is CommonJS-only and does not support ES Modules.
fs-db mixin
wrong:
```
import { fsDbMixin } from 'git-node-fs/mixins/fs-db';
```
correct:
```
require('js-git/mixins/fs-db')(repo, fsAdapter);
```
The mixin is applied by directly requiring the path and invoking it, typical for older Node.js patterns. It is not exported as a named or default ES module.
fs (Node.js built-in)
wrong:
```
const fs = require('fs');
```
correct:
```
const fs = require('node:fs');
```
While 'require("fs")' works, it's best practice in modern Node.js to use the 'node:' prefix for built-in modules to avoid ambiguity with npm packages named 'fs'.

Quickstart

This quickstart demonstrates how to set up a `js-git` repository object with `git-node-fs` to enable local filesystem interaction for Git operations.

const path = require('node:path');
const fsAdapter = require('git-node-fs');

// Initialize a repository object (this is a js-git concept)
const repo = {};

// Point the repository to a .git directory
// For a non-bare repository, it would be the .git folder within the worktree.
// For a bare repository, it would be the bare repo directory itself.
repo.rootPath = path.join(__dirname, '.git');

// Mix in the filesystem database adapter from git-node-fs into the repo object
// This allows js-git operations to interact with the local filesystem.
require('js-git/mixins/fs-db')(repo, fsAdapter);

console.log('Repository configured for git-node-fs:');
console.log(repo);

// At this point, `repo` can be used with other js-git mixins to perform
// Git operations like reading commits, trees, blobs, etc.
// Example (requires more js-git setup):
// const { readCommit } = require('js-git/mixins/walkers')(repo);
// readCommit('HEAD', (err, commit) => {
//   if (err) { console.error('Error reading commit:', err); return; }
//   console.log('HEAD commit:', commit.short); // Assuming a 'short' property exists or similar.
// });

view raw JSON →