JS-Git

Common errors

• SyntaxError: await is only valid in async functions and the top level bodies of modules

  cause Attempting to use `yield` within an `async function` or `await` with a generator-based function without proper wrapping, or trying to use `await` with `js-git`'s generator-style APIs directly.
  fix Wrap generator functions with a generator runner (e.g., `gen-run`) or ensure `yield` is used only within a generator context, not directly with `async/await`. For modern async/await, you'd need a compatibility layer or a different library.

• TypeError: repo.createTree is not a function

  cause The `create-tree` mixin (or any other required mixin) was not applied to the `repo` object, meaning the method was never added.
  fix Ensure `require('js-git/mixins/create-tree')(repo);` (and all other necessary mixins for the methods you intend to use) has been called to augment the `repo` object with the desired functionalities.

• Error: Cannot find module 'js-git/lib/modes'

  cause Incorrect module path or attempting to use `import` syntax in an environment that only supports CommonJS `require()` for this package, or vice-versa.
  fix Verify the module path is correct relative to the `node_modules` directory. Ensure your environment supports CommonJS `require()` statements, as `js-git` does not ship with ES Module exports.

• TypeError: someAction(...) is not a function (when trying to use callback style)

  cause When using `js-git`'s callback-style APIs, if a callback is not provided, the function returns a partially applied function. This error occurs if that returned function is not subsequently invoked with the callback.
  fix When using the callback style, ensure the callback function is provided as the last argument to the `js-git` API call: `someAction(args, function (err, value) { ... });`. If you intended to curry, make sure to invoke the curried function: `someAction(args)(function (err, value) { ... });`.

Warnings

• breaking Reliance on ES6 Generators and `yield` for async operations. This library's primary asynchronous control flow pattern uses ES6 generators with `yield`, often orchestrated by external runners like `gen-run`. This is not compatible with modern `async/await` syntax directly without transpilation or wrapping.
  Fix: Use a generator runner like `gen-run` or transpile with tools like `regenerator`. Do not attempt to use `async/await` directly with `yield` statements.
• gotcha CommonJS Module System Only. `js-git` exclusively uses CommonJS `require()` for module loading and is not directly compatible with ES Modules `import` syntax.
  Fix: Ensure your project is configured to use CommonJS modules or use dynamic `import()` if absolutely necessary, though direct `require()` is the intended usage.
• gotcha Manual Mixin Composition Required. Unlike many modern libraries, `js-git` requires developers to manually apply each desired functionality (e.g., storage, tree operations, walkers) as 'mixins' to a base repository object. Forgetting a mixin will result in missing methods.
  Fix: Review the documentation for required mixins and ensure all necessary functionalities are explicitly applied to your repository object using `require('js-git/mixins/...')(...)(repo)`.
• breaking Project Abandoned: `js-git` has not been actively maintained for several years (since approximately 2015). This means no new features, bug fixes, or security patches will be released, and it may not be compatible with newer Node.js versions or browser environments without significant effort.
  Fix: Consider alternative, actively maintained Git-related libraries for JavaScript, or be prepared to fork and maintain `js-git` yourself if specific features are indispensable.

Install

• npm install js-git npm
• yarn add js-git yarn
• pnpm add js-git pnpm

Imports

• modes
  wrong:

  import { modes } from 'js-git/lib/modes';

  correct:

  var modes = require('js-git/lib/modes');

  JS-Git uses CommonJS `require()` exclusively. There is no ES Module export.
• memDbMixin
  wrong:

  import memDbMixin from 'js-git/mixins/mem-db';

  correct:

  require('js-git/mixins/mem-db')(repo);

  Mixins are functions that directly modify the `repo` object when called with it, not modules to be imported and assigned.
• createTreeMixin
  wrong:

  import { createTree } from 'js-git/mixins/create-tree';

  correct:

  require('js-git/mixins/create-tree')(repo);

  Like other mixins, `create-tree` is a CommonJS module that exports a function to augment the `repo` object.
• run
  wrong:

  import run from 'gen-run';

  correct:

  var run = require('gen-run');

  The `gen-run` dependency also uses CommonJS `require()`.

Quickstart

Demonstrates initializing an in-memory Git repository with various mixins and executing a basic tree creation operation using generator-based async control flow.

var modes = require('js-git/lib/modes');
var run = require('gen-run');

// Create a repo by creating a plain object.
var repo = {};

// Mix in various functionalities to the repo object
require('js-git/mixins/mem-db')(repo); // Provides in-memory storage
require('js-git/mixins/create-tree')(repo); // Adds high-level tree creation API
require('js-git/mixins/pack-ops')(repo); // Methods for packfile streams
require('js-git/mixins/walkers')(repo); // Algorithms for walking history/trees
require('js-git/mixins/read-combiner')(repo); // Combines parallel requests
require('js-git/mixins/formats')(repo); // Makes object interface less strict

run(function*() {
  try {
    // Example: Creating a simple tree object
    const treeHash = yield repo.createTree([
      { mode: modes.blob, path: "README.md", content: "Hello, js-git!" },
      { mode: modes.tree, path: "src", entries: [] } // An empty tree folder
    ]);
    console.log("Created tree with hash:", treeHash);

    // You could now save this tree as part of a commit, fetch blobs, etc.
    // For instance, loading the content of README.md (requires other mixins and setup)
    // const readmeBlob = yield repo.loadAs('blob', 'hash_of_readme_blob');
    // console.log("README content:", readmeBlob.toString());
    
    console.log("Repo initialized and a basic tree created.");
  } catch (err) {
    console.error("An error occurred:", err);
  }
});