Diff and Status

Understanding your repository’s state is crucial for effective Git workflows. This guide covers how to check status, view diffs, and inspect changes using useGit.

Checking Repository Status

Basic Status

View the working tree status:

import { status } from 'usegit';

// Get human-readable status
const statusOutput = await status();
console.log(statusOutput);

Short Status Format

Use compact output for scripts and tools:

import { status } from 'usegit';

// Short format with branch info
const shortStatus = await status(undefined, {
  flags: ['--short', '--branch']
});
console.log(shortStatus);
// ## main...origin/main
//  M src/index.ts
// ?? new-file.ts

Porcelain Format

Machine-readable format for parsing:

import { status } from 'usegit';

// Porcelain format (stable across Git versions)
const porcelain = await status(undefined, {
  flags: ['--porcelain']
});

The --porcelain flag provides a stable, parseable format designed for use in scripts and tools. It won’t change across Git versions, making it ideal for automation.

Status for Specific Paths

Limit status to particular files or directories:

import { status } from 'usegit';

// Check status of specific paths
const srcStatus = await status(['src', 'package.json']);
console.log(srcStatus);

Working Tree State

Check if Working Tree is Clean

Determine if there are uncommitted changes:

import { isCleanWorkingTree } from 'usegit';

const isClean = await isCleanWorkingTree();
if (isClean) {
  console.log('Working tree is clean - ready to switch branches');
} else {
  console.log('You have uncommitted changes');
}

Check if Repository is Dirty

Get the dirty status with details:

import { isDirty } from 'usegit';

// Check all changes (tracked + untracked)
const dirtyStatus = await isDirty();
if (dirtyStatus) {
  console.log('Repository has changes:', dirtyStatus);
}

// Check only tracked file modifications
const trackedChanges = await isDirty({ trackedOnly: true });
if (trackedChanges) {
  console.log('Tracked files modified:', trackedChanges);
}

Check for Untracked Files

Identify new files not yet tracked:

import { hasUntrackedFiles, getUntrackedFiles } from 'usegit';

// Check if any untracked files exist
const hasUntracked = await hasUntrackedFiles();
console.log('Has untracked files:', hasUntracked);

// Get list of untracked files
const untrackedFiles = await getUntrackedFiles();
console.log('Untracked files:', untrackedFiles);
// ['new-feature.ts', 'temp.txt']

Viewing Diffs

Working Tree Diff

View changes in your working directory:

import { diff } from 'usegit';

// Show all unstaged changes
const changes = await diff();
console.log(changes);

Staged Changes Diff

See what’s staged for commit:

import { diffStaged } from 'usegit';

// View staged changes
const stagedDiff = await diffStaged();
console.log('Changes to be committed:', stagedDiff);

// View staged changes for specific files
const fileDiff = await diffStaged(['src/index.ts']);
console.log(fileDiff);

Diff Between Commits

Compare different commits:

import { diff, diffCommits } from 'usegit';

// Compare HEAD with previous commit
const lastCommitDiff = await diff(['HEAD~1', 'HEAD']);
console.log(lastCommitDiff);

// Using the dedicated function
const commitDiff = await diffCommits('HEAD~2', 'HEAD');
console.log(commitDiff);

Diff Against HEAD

Compare working tree with the last commit:

import { diffHead } from 'usegit';

// Show all changes since last commit
const headDiff = await diffHead();
console.log(headDiff);

Diff Statistics

Basic Diff Stats

Get numerical statistics about changes:

import { diffStats } from 'usegit';

// Get statistics for working tree
const stats = await diffStats();
console.log(stats);
// { files: 3, additions: 24, deletions: 6, binaryFiles: 0 }

Staged Diff Stats

Statistics for staged changes:

import { diffStatsStaged } from 'usegit';

const stagedStats = await diffStatsStaged();
console.log('Staged changes:', stagedStats);
// { files: 2, additions: 15, deletions: 3, binaryFiles: 0 }

Commit Diff Stats

Compare statistics between commits:

import { diffStatsCommits } from 'usegit';

const commitStats = await diffStatsCommits('main', 'feature/new-api');
console.log('Changes between branches:', commitStats);

Diff Stat Summary

Get a summary string of changes:

import { diffStatSummary, diffStatStagedSummary } from 'usegit';

// Summary for working tree
const summary = await diffStatSummary();
console.log(summary);
// "3 files changed, 24 insertions(+), 6 deletions(-)"

// Summary for staged changes
const stagedSummary = await diffStatStagedSummary();
console.log(stagedSummary);

File-Based Operations

Get Changed Files

List files modified in working tree:

import { getChangedFiles } from 'usegit';

const changedFiles = await getChangedFiles();
console.log('Modified files:', changedFiles);
// ['src/index.ts', 'README.md', 'package.json']

Get Staged Files

List files staged for commit:

import { getStagedFiles } from 'usegit';

const stagedFiles = await getStagedFiles();
console.log('Staged files:', stagedFiles);
// ['src/utils.ts', 'tests/utils.test.ts']

Count Changed Files

Get the number of changed files:

import { changedFileCount, stagedFileCount } from 'usegit';

// Count modified files
const changedCount = await changedFileCount();
console.log(`${changedCount} files modified`);

// Count staged files
const stagedCount = await stagedFileCount();
console.log(`${stagedCount} files staged`);

Specialized Diff Checks

Check for Binary Changes

Detect binary file modifications:

import { hasBinaryChanges } from 'usegit';

const hasBinary = await hasBinaryChanges();
if (hasBinary) {
  console.log('Warning: Binary files have been modified');
}

Check for Whitespace-Only Changes

Identify commits with only whitespace changes:

import { hasOnlyWhitespaceChanges } from 'usegit';

const onlyWhitespace = await hasOnlyWhitespaceChanges();
if (onlyWhitespace) {
  console.log('Changes are only whitespace');
}

Check for EOL-Only Changes

Detect changes that are only line ending differences:

import { hasOnlyEOLChanges } from 'usegit';

const onlyEOL = await hasOnlyEOLChanges();
if (onlyEOL) {
  console.log('Changes are only line ending differences');
}

Check if Diff Exists

Quickly check if there are any changes:

import { hasDiff, hasStagedDiff } from 'usegit';

// Check for any unstaged changes
const hasChanges = await hasDiff();
if (hasChanges) {
  console.log('You have unstaged changes');
}

// Check for staged changes
const hasStaged = await hasStagedDiff();
if (hasStaged) {
  console.log('You have changes ready to commit');
}

Advanced Diff Options

Diff with Stat Flag

Combine diff with statistics:

import { diff } from 'usegit';

// Show diff with stat summary
const diffWithStats = await diff(undefined, undefined, {
  flags: ['--stat']
});
console.log(diffWithStats);

Diff Specific Files

View changes for particular files:

import { diff, diffFiles } from 'usegit';

// Diff specific files
const fileDiff = await diff(undefined, ['src/index.ts', 'src/utils.ts']);
console.log(fileDiff);

// Using diffFiles
const specificDiff = await diffFiles(['README.md']);
console.log(specificDiff);

Diff Range

Compare across a range of commits:

import { diffRange } from 'usegit';

// Diff a range of commits
const rangeDiff = await diffRange('main..feature/new-api');
console.log(rangeDiff);

Real-World Workflows

Pre-Commit Inspection

Review changes before committing:

Check repository status

import { status, isDirty } from 'usegit';

const dirtyStatus = await isDirty();
if (!dirtyStatus) {
  console.log('No changes to commit');
  process.exit(0);
}

const statusOutput = await status();
console.log(statusOutput);

Review changed files

import { getChangedFiles } from 'usegit';

const files = await getChangedFiles();
console.log('Files with changes:', files);

Inspect detailed changes

import { diff, diffStats } from 'usegit';

const stats = await diffStats();
console.log('Change statistics:', stats);

const changes = await diff();
console.log('Detailed diff:', changes);

Review what will be committed

import { diffStaged, diffStatsStaged } from 'usegit';

const stagedStats = await diffStatsStaged();
console.log('Staged:', stagedStats);

const stagedDiff = await diffStaged();
console.log('Changes to commit:', stagedDiff);

Change Validation

Validate changes before operations:

import {
  isCleanWorkingTree,
  hasBinaryChanges,
  hasOnlyWhitespaceChanges,
  diffStats,
  status
} from 'usegit';

async function validateChanges() {
  // Ensure working tree is clean for branch switch
  const isClean = await isCleanWorkingTree();
  if (!isClean) {
    console.error('Cannot switch branches: uncommitted changes exist');
    const statusOutput = await status();
    console.log(statusOutput);
    return false;
  }

  // Check for binary changes that might need special handling
  const hasBinary = await hasBinaryChanges();
  if (hasBinary) {
    console.warn('Warning: Binary files modified');
  }

  // Skip commits that are only whitespace
  const onlyWhitespace = await hasOnlyWhitespaceChanges();
  if (onlyWhitespace) {
    console.log('Skipping commit: only whitespace changes');
    return false;
  }

  // Get change statistics
  const stats = await diffStats();
  console.log(`Ready to commit: ${stats.files} files, +${stats.additions} -${stats.deletions}`);
  
  return true;
}

validateChanges();

Comprehensive Status Report

Generate a complete repository status report:

import {
  currentBranch,
  status,
  isCleanWorkingTree,
  hasUntrackedFiles,
  getUntrackedFiles,
  getChangedFiles,
  getStagedFiles,
  diffStats,
  diffStatsStaged
} from 'usegit';

async function generateStatusReport() {
  console.log('=== Repository Status Report ===\n');

  // Current branch
  const branch = await currentBranch();
  console.log(`Branch: ${branch}\n`);

  // Working tree state
  const isClean = await isCleanWorkingTree();
  console.log(`Working Tree: ${isClean ? 'CLEAN' : 'DIRTY'}\n`);

  if (!isClean) {
    // Untracked files
    const hasUntracked = await hasUntrackedFiles();
    if (hasUntracked) {
      const untrackedFiles = await getUntrackedFiles();
      console.log('Untracked Files:');
      untrackedFiles.forEach(file => console.log(`  - ${file}`));
      console.log();
    }

    // Modified files
    const changedFiles = await getChangedFiles();
    if (changedFiles.length > 0) {
      console.log('Modified Files:');
      changedFiles.forEach(file => console.log(`  - ${file}`));
      console.log();
    }

    // Staged files
    const stagedFiles = await getStagedFiles();
    if (stagedFiles.length > 0) {
      console.log('Staged Files:');
      stagedFiles.forEach(file => console.log(`  - ${file}`));
      console.log();

      const stagedStats = await diffStatsStaged();
      console.log('Staged Changes:');
      console.log(`  Files: ${stagedStats.files}`);
      console.log(`  Additions: +${stagedStats.additions}`);
      console.log(`  Deletions: -${stagedStats.deletions}`);
      console.log();
    }

    // Unstaged statistics
    const workingStats = await diffStats();
    console.log('Working Tree Changes:');
    console.log(`  Files: ${workingStats.files}`);
    console.log(`  Additions: +${workingStats.additions}`);
    console.log(`  Deletions: -${workingStats.deletions}`);
    console.log();
  }

  // Full status output
  console.log('Detailed Status:');
  const statusOutput = await status();
  console.log(statusOutput);
}

generateStatusReport();

Complete Example

Here’s a comprehensive example showing various inspection operations:

import {
  status,
  diff,
  diffStaged,
  diffStats,
  isCleanWorkingTree,
  getChangedFiles,
  getStagedFiles,
  hasBinaryChanges,
  currentBranch
} from 'usegit';

async function inspectRepository() {
  try {
    // Show current branch
    const branch = await currentBranch();
    console.log(`Current branch: ${branch}\n`);

    // Check if there are changes
    const isClean = await isCleanWorkingTree();
    if (isClean) {
      console.log('Working tree is clean. Nothing to inspect.');
      return;
    }

    // Get overview of changes
    console.log('=== Working Tree Changes ===');
    const changedFiles = await getChangedFiles();
    console.log('Modified files:', changedFiles);

    const stats = await diffStats();
    console.log(`Statistics: ${stats.files} files, +${stats.additions}, -${stats.deletions}\n`);

    // Check for binary files
    const hasBinary = await hasBinaryChanges();
    if (hasBinary) {
      console.log('⚠️  Binary files detected\n');
    }

    // Show staged changes
    const stagedFiles = await getStagedFiles();
    if (stagedFiles.length > 0) {
      console.log('=== Staged Changes ===');
      console.log('Staged files:', stagedFiles);
      
      const stagedDiff = await diffStaged();
      console.log('Diff:', stagedDiff.substring(0, 500), '...\n');
    }

    // Show unstaged changes
    const changes = await diff();
    if (changes) {
      console.log('=== Unstaged Changes ===');
      console.log(changes.substring(0, 500), '...\n');
    }

    // Full status
    console.log('=== Full Status ===');
    const statusOutput = await status();
    console.log(statusOutput);

  } catch (error) {
    console.error('Error inspecting repository:', error);
  }
}

inspectRepository();

Get Started

Core Concepts

Examples

​Checking Repository Status

​Basic Status

​Short Status Format

​Porcelain Format

​Status for Specific Paths

​Working Tree State

​Check if Working Tree is Clean

​Check if Repository is Dirty

​Check for Untracked Files

​Viewing Diffs

​Working Tree Diff

​Staged Changes Diff

​Diff Between Commits

​Diff Against HEAD

​Diff Statistics

​Basic Diff Stats

​Staged Diff Stats

​Commit Diff Stats

​Diff Stat Summary

​File-Based Operations

​Get Changed Files

​Get Staged Files

​Count Changed Files

​Specialized Diff Checks

​Check for Binary Changes

​Check for Whitespace-Only Changes

​Check for EOL-Only Changes

​Check if Diff Exists

​Advanced Diff Options

​Diff with Stat Flag

​Diff Specific Files

​Diff Range

​Real-World Workflows

​Pre-Commit Inspection

​Change Validation

​Comprehensive Status Report

​Complete Example

​Next Steps

Basic Workflow

Branch Management

Build docs developers (and LLMs) love

Checking Repository Status

Basic Status

Short Status Format

Porcelain Format

Status for Specific Paths

Working Tree State

Check if Working Tree is Clean

Check if Repository is Dirty

Check for Untracked Files

Viewing Diffs

Working Tree Diff

Staged Changes Diff

Diff Between Commits

Diff Against HEAD

Diff Statistics

Basic Diff Stats

Staged Diff Stats

Commit Diff Stats

Diff Stat Summary

File-Based Operations

Get Changed Files

Get Staged Files

Count Changed Files

Specialized Diff Checks

Check for Binary Changes

Check for Whitespace-Only Changes

Check for EOL-Only Changes

Check if Diff Exists

Advanced Diff Options

Diff with Stat Flag

Diff Specific Files

Diff Range

Real-World Workflows

Pre-Commit Inspection

Change Validation

Comprehensive Status Report

Complete Example

Next Steps