staged-git-files

What is staged-git-files?

The 'staged-git-files' npm package is used to retrieve information about staged files in a Git repository. It allows developers to programmatically access details about files that have been added to the staging area, which can be useful for pre-commit hooks, linting, and other automated workflows.

What are staged-git-files's main functionalities?

List Staged Files

This feature allows you to list all staged files in the repository. The 'ACM' argument stands for Added, Copied, and Modified files. The callback function receives an error object and a results array containing details about each staged file.

const sgf = require('staged-git-files');

sgf('ACM', (err, results) => {
  if (err) throw err;
  console.log(results);
});

Filter Staged Files by Status

This feature allows you to filter staged files by their status. In this example, 'A' stands for Added files. The callback function receives an error object and a results array containing details about each added file.

const sgf = require('staged-git-files');

sgf('A', (err, results) => {
  if (err) throw err;
  console.log(results);
});

Custom File Status Query

This feature allows you to create a custom query for staged files by specifying an array of status codes. In this example, it retrieves files that are either Added ('A') or Modified ('M'). The callback function receives an error object and a results array containing details about each file matching the query.

const sgf = require('staged-git-files');

sgf(['A', 'M'], (err, results) => {
  if (err) throw err;
  console.log(results);
});

Other packages similar to staged-git-files

simple-git

The 'simple-git' package is a lightweight interface for running Git commands in any Node.js application. It provides a more comprehensive set of Git functionalities compared to 'staged-git-files', including committing, pushing, and pulling changes, as well as retrieving the status of the repository.

isomorphic-git

The 'isomorphic-git' package is a pure JavaScript implementation of Git that works in both Node.js and browser environments. It offers a wide range of Git functionalities, including cloning repositories, committing changes, and managing branches. It is more versatile than 'staged-git-files' but also more complex to use.

nodegit

The 'nodegit' package is a native Node.js binding to the libgit2 library, providing a full suite of Git functionalities. It allows for more advanced Git operations, such as merging branches and handling submodules, making it more powerful but also more complex than 'staged-git-files'.

README

Staged Git Files

This module returns an array of staged files and their status acording to git.

Usage

npm install staged-git-files

var sgf = require("staged-git-files");
sgf(function(err, results){
	//WHAT EVER YOU SO PLEASE
});

Example Results

[
	{
		"filename": "package.json",
		"status": "Added"
	},
	{
		"filename": "readme.md",
		"status": "Modified"
	},
	{
		"filename": "index.js",
		"status": "Renamed"
	}
]

Usage as a cli

$ sgf
Added package.json
Modified readme.md
Renamed index.js

API

sgf(filter, callback)

Get a list of staged git files

• options:
  • filter: string of git status codes. No spaces
  • relative: boolean, tells diff to run in relative mode
• callback:
  • err: the error
  • results: file object array.

If you omit a callback sgf will return a promise. How to use with async/await:

async function main () {
	const stagedFiles = await sgf();
}

main();

sgf.getHead(callback)

Get head that will be used in the diff to ID which files are waiting to be staged.

• callback
  • err: the error
  • head: the git commit id which is aliased to head.

sgf.readFile(filename, [options], callback)

This is a proxy for fs.readFile with one change. The filename will be relative to the sgf.cwd

sgf.debug

Boolean that flips logging on and off. By default this is false. If true, all git commands will be console logged.

sgf.includeContent

If true, include content will add a content or err param to the file object.

• Default Value: false
• Content Param: the content of the file staged
• Err Param: the error message received while trying to read the file.

sgf.cwd

The current working directory. AKA: where the .git folder you care about is.

Default Value: is equal to process.cwd() of your app.g

Statuses

SGF-Status (git status code)

• Added (A)
• Copied (C)
• Deleted (D)
• Modified (M)
• Renamed (R)
• Type-Change (T) [i.e. regular file, symlink, submodule, etc.]
• Unmerged (U)
• Unknown (X)

Changelog

1.3.0

• Adds --relative support to allow the listing of files in the current directoy. #21 by mgrsskls.