Git Er Done

Utility for dealing with modified, created, deleted files since a git commit.

!image

Install

``bash
npm install git-er-done
`

Usage

$3

`js
const { gitDetails } = require('git-er-done')

// Git commit ref / branch to check against. Default is 'master'
const GIT_COMMIT_REF = '9f63b23ec99e36a176d73909fc67a39dc3bd56b7'

gitDetails({
base: GIT_COMMIT_REF,
// Optional: specify working directory (defaults to process.cwd())
// cwd: '/path/to/repo'
}).then((git) => {
/* git data returns
{
fileMatch: [Function], <-- Lookup function
modifiedFiles: [ Array of modified files ],
createdFiles: [ Array of created files ],
deletedFiles: [ Array of deleted files ],
commits: [ Array of commits ],
lastCommit: { Object with last commit info },
linesOfCode: [AsyncFunction: linesOfCode],
dir: String path to git repo
}
*/

if (git.modifiedFiles.length) {
// Some files have changed
}

if (git.createdFiles.length) {
// Some files have been created
}

if (git.deletedFiles.length) {
// Some files have been deleted
}
})
`

$3

You can call gitDetails() without any options to get info from the current HEAD:

`js
const { gitDetails } = require('git-er-done')

const git = await gitDetails()
console.log('Modified files:', git.modifiedFiles)
console.log('Created files:', git.createdFiles)
console.log('Deleted files:', git.deletedFiles)
`

$3

All functions support a cwd option to run git commands in a different directory:

`js
const { gitDetails, getCurrentBranch, getLastCommit } = require('git-er-done')

// Run git commands in a different repo
const git = await gitDetails({
base: 'main',
cwd: '/path/to/other/repo'
})

const branch = await getCurrentBranch({ cwd: '/path/to/other/repo' })
const lastCommit = await getLastCommit({ cwd: '/path/to/other/repo' })
`

$3

Use includeWorkingChanges to compare against uncommitted changes in the working directory:

`js
const { gitDetails } = require('git-er-done')

const git = await gitDetails({
base: 'main',
includeWorkingChanges: true
})

console.log('Uncommitted changes:', git.modifiedFiles)
`

$3

`js
const { gitDetails } = require('git-er-done')

const git = await gitDetails({
base: 'main',
head: 'feature-branch'
})

const totalLines = await git.linesOfCode()
console.log(Total lines changed: ${totalLines})
`

$3

Access detailed commit information including author, committer, and subject:

`js
const { gitDetails } = require('git-er-done')

const git = await gitDetails({ base: 'main' })

// Access commits array
git.commits.forEach((commit) => {
console.log('SHA:', commit.sha)
console.log('Author:', commit.author.name, commit.author.email)
console.log('Committer:', commit.committer.name)
console.log('Subject:', commit.subject)
console.log('Sanitized Subject:', commit.sanitizedSubject)
console.log('---')
})

// Access the last commit
console.log('Last commit:', git.lastCommit)
`

$3

Use glob patterns to match specific files. You can also use negation patterns:

`js
const { gitDetails } = require('git-er-done')

const git = await gitDetails({ base: 'main' })

// Simple pattern matching
const srcCode = git.fileMatch('src/*/.js')
/* srcCode returns object with:
{
modified: Boolean,
modifiedFiles: Array,
created: Boolean,
createdFiles: Array,
deleted: Boolean,
deletedFiles: Array,
edited: Boolean,
editedFiles: Array
}
*/

if (srcCode.edited) {
console.log('Source code has been edited')
console.log('Modified files:', srcCode.modifiedFiles)
console.log('Created files:', srcCode.createdFiles)
}

// Match with negation - find all JSON files except package.json
const jsonFiles = git.fileMatch('/.json', '!**/package.json')
if (jsonFiles.modified) {
console.log('Non-package JSON files modified:', jsonFiles.modifiedFiles)
}
if (jsonFiles.created) {
console.log('Non-package JSON files created:', jsonFiles.createdFiles)
}

// Check markdown files
const mdFiles = git.fileMatch('*/.md')
if (mdFiles.edited) {
// Do stuff because markdown files are changed
console.log('All markdown changes:', mdFiles.editedFiles)
}
`

$3

Get git timestamps for when files were created and last modified:

`js
const { getFileDates, getFileModifiedTimeStamp, getFileCreatedTimeStamp } = require('git-er-done')

// Get both dates efficiently (recommended)
const dates = await getFileDates('src/index.js')
console.log('Created:', dates.createdDate)
console.log('Modified:', dates.modifiedDate)
console.log('Created timestamp:', dates.created) // Unix timestamp in seconds
console.log('Modified timestamp:', dates.modified) // Unix timestamp in seconds

// Or get just modified date
const modifiedTimestamp = await getFileModifiedTimeStamp('README.md')
console.log('Last modified:', new Date(modifiedTimestamp * 1000))

// Or get just created date
const createdTimestamp = await getFileCreatedTimeStamp('README.md')
console.log('First committed:', new Date(createdTimestamp * 1000))

// Get dates for multiple files (pass an array)
const files = ['README.md', 'package.json', 'src/index.js']
const fileDates = await getFileDates(files)

for (const [file, info] of Object.entries(fileDates)) {
if (!info.error) {
console.log(${file}: last modified ${info.modifiedDate.toISOString()})
}
}
`

$3

The fileMatch function returns detailed information about matched files:

`js
const { gitDetails } = require('git-er-done')

const git = await gitDetails({ base: 'main' })

const testFiles = git.fileMatch('*/.test.js')

// Access individual arrays
console.log('Modified test files:', testFiles.modifiedFiles)
console.log('Created test files:', testFiles.createdFiles)
console.log('Deleted test files:', testFiles.deletedFiles)
console.log('All edited test files:', testFiles.editedFiles)

// Check if any test files changed
if (testFiles.edited) {
console.log('Tests have been modified - run test suite')
}
`

$3

`js
const { getGitRoot } = require('git-er-done')

const root = await getGitRoot()
console.log('Git root:', root) // '/Users/you/your-repo'

// With cwd option
const otherRoot = await getGitRoot('/path/to/other/repo')
`

$3

`js
const { getCurrentBranch } = require('git-er-done')

const branch = await getCurrentBranch()
console.log('Current branch:', branch) // 'main'

// With cwd option
const otherBranch = await getCurrentBranch({ cwd: '/path/to/other/repo' })
`

$3

Retrieve the contents of a file as it existed at a specific commit:

`js
const { getFileAtCommit } = require('git-er-done')

// Get file contents from previous commit
const previousVersion = await getFileAtCommit('src/index.js', 'HEAD~1')
console.log('Previous version:', previousVersion)

// Get file at specific SHA
const oldVersion = await getFileAtCommit('package.json', 'abc123')

// With cwd option for running in a different directory
const contents = await getFileAtCommit('src/app.js', 'main', {
cwd: '/path/to/other/repo'
})
`

$3

`js
const { getRemotes, getRemote } = require('git-er-done')

// Get all remotes
const remotes = await getRemotes()
console.log('All remotes:', Object.keys(remotes)) // ['origin', 'upstream']
console.log('Origin URL:', remotes.origin.url)

// Get a specific remote
const origin = await getRemote('origin')
console.log('Origin:', origin)
// { name: 'origin', url: 'git@github.com:user/repo.git', fetchUrl: '...', pushUrl: '...' }
`

$3

Import only what you need for smaller bundles:

`js
// Individual imports
const { getCommit } = require('git-er-done/get-commit')
const { getAllCommits } = require('git-er-done/get-all-commits')
const { getFirstCommit } = require('git-er-done/get-first-commit')
const { getLastCommit } = require('git-er-done/get-last-commit')
const { gitDetails } = require('git-er-done/get-details')
const { getGitRoot } = require('git-er-done/get-root')
const { getCurrentBranch } = require('git-er-done/get-current-branch')
const { getGitFiles } = require('git-er-done/get-files')
const { getFileAtCommit } = require('git-er-done/get-file-at-commit')
const { getFileDates, getFileModifiedTimeStamp, getFileCreatedTimeStamp } = require('git-er-done/get-file-dates')
const { getRemotes, getRemote } = require('git-er-done/get-remotes')
const { getFormattedDiff } = require('git-er-done/get-diff-formatted')
`

Examples

Check out the examples directory for more use cases:

$3

`bash
node examples/get-git-data.js
node examples/code-review-helper.js
node examples/monorepo-package-detection.js
node examples/serverless-monorepo-detection.js
``

Prior art

This was originally found in danger.js and extracted into this utility

- @netlify/build
- run-if-diff CLI