or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-operations.mdbranch-operations.mddata-operations.mdfile-operations.mdindex.mdinformation-status.mdremote-operations.mdrepository-management.md
tile.json

information-status.mddocs/

Information and Status

Functions for querying repository state, status, and retrieving Git information. These functions return useful data through their callbacks for inspecting repository state.

Capabilities

Repository Status

Shows the working tree status using git status. Returns status output through callback.

/**
 * Shows git repository status using git status
 * @param opt - Configuration options (optional)
 * @param cb - Callback function receiving (err, stdout)
 */
function status(opt?: StatusOptions, cb?: StatusCallback): void;
function status(cb?: StatusCallback): void;

interface StatusOptions extends BaseOptions {
  // Inherits: cwd, args, quiet, maxBuffer
}

interface StatusCallback {
  (err?: Error, stdout?: string): void;
}

Usage Examples:

const git = require('gulp-git');

// Basic status
git.status(function(err, stdout) {
  if (err) throw err;
  console.log('Repository status:');
  console.log(stdout);
});

// Porcelain status (machine-readable)
git.status({ args: '--porcelain' }, function(err, stdout) {
  if (err) throw err;
  const files = stdout.split('\n').filter(line => line.trim());
  console.log('Modified files:', files.length);
});

// Short status
git.status({ args: '--short' }, function(err, stdout) {
  if (err) throw err;
  console.log('Short status:', stdout);
});

// Status with untracked files
git.status({ args: '--untracked-files=all' }, function(err, stdout) {
  if (err) throw err;
  console.log('Status with all untracked files:', stdout);
});

Git Rev-Parse

Executes git rev-parse for getting Git repository information like commit hashes, branch names, etc.

/**
 * Executes git rev-parse for getting git information
 * @param opt - Configuration options (optional)
 * @param cb - Callback function receiving (err, result)
 */
function revParse(opt?: RevParseOptions, cb?: RevParseCallback): void;
function revParse(cb?: RevParseCallback): void;

interface RevParseOptions extends BaseOptions {
  // Inherits: cwd, args, quiet, maxBuffer
}

interface RevParseCallback {
  (err?: Error, result?: string): void;
}

Usage Examples:

// Get current commit hash
git.revParse({ args: 'HEAD' }, function(err, hash) {
  if (err) throw err;
  console.log('Current commit:', hash.trim());
});

// Get short commit hash
git.revParse({ args: '--short HEAD' }, function(err, hash) {
  if (err) throw err;
  console.log('Short commit hash:', hash.trim());
});

// Get current branch name
git.revParse({ args: '--abbrev-ref HEAD' }, function(err, branch) {
  if (err) throw err;
  console.log('Current branch:', branch.trim());
});

// Get repository root directory
git.revParse({ args: '--show-toplevel' }, function(err, root) {
  if (err) throw err;
  console.log('Repository root:', root.trim());
});

// Check if inside git repository
git.revParse({ args: '--is-inside-work-tree' }, function(err, result) {
  if (err) {
    console.log('Not inside a git repository');
    return;
  }
  console.log('Inside git repository:', result.trim() === 'true');
});

// Get remote URL
git.revParse({ args: '--symbolic-full-name @{upstream}' }, function(err, upstream) {
  if (err) {
    console.log('No upstream configured');
    return;
  }
  console.log('Upstream branch:', upstream.trim());
});

Show Branch

Shows Git branch information using git show-branch. Useful for displaying branch relationships and commits.

/**
 * Shows git branch information using git show-branch
 * @param opt - Configuration options (optional)
 * @param cb - Callback function receiving (err, result)
 */
function showBranch(opt?: ShowBranchOptions, cb?: ShowBranchCallback): void;
function showBranch(cb?: ShowBranchCallback): void;

interface ShowBranchOptions extends BaseOptions {
  // Inherits: cwd, args, quiet, maxBuffer
}

interface ShowBranchCallback {
  (err?: Error, result?: string): void;
}

Usage Examples:

// Show current branch
git.showBranch(function(err, result) {
  if (err) throw err;
  console.log('Branch information:', result);
});

// List all branches
git.showBranch({ args: '--list -a' }, function(err, result) {
  if (err) throw err;
  console.log('All branches:', result);
});

// Show branch with more details
git.showBranch({ args: '--more=10' }, function(err, result) {
  if (err) throw err;
  console.log('Branch details:', result);
});

// Show independent branches
git.showBranch({ args: '--independent' }, function(err, result) {
  if (err) throw err;
  console.log('Independent branches:', result);
});

Common Patterns

Repository Health Check

const gulp = require('gulp');
const git = require('gulp-git');

gulp.task('health-check', function(done) {
  console.log('Checking repository health...');
  
  // Check if in git repository
  git.revParse({ args: '--is-inside-work-tree' }, function(err, result) {
    if (err) {
      console.log('❌ Not a git repository');
      return done();
    }
    
    // Get current branch
    git.revParse({ args: '--abbrev-ref HEAD' }, function(err, branch) {
      if (err) return done(err);
      console.log('✓ Current branch:', branch.trim());
      
      // Check repository status
      git.status({ args: '--porcelain' }, function(err, status) {
        if (err) return done(err);
        
        const changes = status.split('\n').filter(line => line.trim()).length;
        if (changes === 0) {
          console.log('✓ Working tree clean');
        } else {
          console.log(`⚠ ${changes} uncommitted changes`);
        }
        
        done();
      });
    });
  });
});

Branch Information

gulp.task('branch-info', function(done) {
  // Get current branch
  git.revParse({ args: '--abbrev-ref HEAD' }, function(err, currentBranch) {
    if (err) return done(err);
    
    console.log('Current branch:', currentBranch.trim());
    
    // Get current commit
    git.revParse({ args: '--short HEAD' }, function(err, commit) {
      if (err) return done(err);
      
      console.log('Current commit:', commit.trim());
      
      // Show branch relationships
      git.showBranch({ args: '--current' }, function(err, branches) {
        if (err) return done(err);
        
        console.log('Branch relationships:');
        console.log(branches);
        done();
      });
    });
  });
});

Repository Statistics

gulp.task('repo-stats', function(done) {
  const stats = {};
  
  // Get repository root
  git.revParse({ args: '--show-toplevel' }, function(err, root) {
    if (err) return done(err);
    stats.root = root.trim();
    
    // Get total commits
    git.exec({ args: 'rev-list --count HEAD' }, function(err, count) {
      if (err) return done(err);
      stats.totalCommits = parseInt(count.trim());
      
      // Get contributors
      git.exec({ args: 'shortlog -sn' }, function(err, contributors) {
        if (err) return done(err);
        stats.contributors = contributors.split('\n').length - 1;
        
        // Get repository size
        git.exec({ args: 'count-objects -vH' }, function(err, objects) {
          if (err) return done(err);
          
          console.log('Repository Statistics:');
          console.log('Root:', stats.root);
          console.log('Total commits:', stats.totalCommits);
          console.log('Contributors:', stats.contributors);
          console.log('Objects info:', objects);
          
          done();
        });
      });
    });
  });
});

Change Detection

function detectChanges(callback) {
  git.status({ args: '--porcelain' }, function(err, stdout) {
    if (err) return callback(err);
    
    const lines = stdout.split('\n').filter(line => line.trim());
    const changes = {
      modified: [],
      added: [],
      deleted: [],
      renamed: [],
      untracked: []
    };
    
    lines.forEach(function(line) {
      const status = line.substring(0, 2);
      const file = line.substring(3);
      
      if (status.includes('M')) changes.modified.push(file);
      if (status.includes('A')) changes.added.push(file);
      if (status.includes('D')) changes.deleted.push(file);
      if (status.includes('R')) changes.renamed.push(file);
      if (status.includes('??')) changes.untracked.push(file);
    });
    
    callback(null, changes);
  });
}

gulp.task('check-changes', function(done) {
  detectChanges(function(err, changes) {
    if (err) return done(err);
    
    console.log('Repository changes:');
    console.log('Modified:', changes.modified.length);
    console.log('Added:', changes.added.length);
    console.log('Deleted:', changes.deleted.length);
    console.log('Renamed:', changes.renamed.length);
    console.log('Untracked:', changes.untracked.length);
    
    done();
  });
});

Commit Validation

function validateCommit(hash, callback) {
  if (!hash) {
    return git.revParse({ args: 'HEAD' }, function(err, currentHash) {
      if (err) return callback(err);
      validateCommit(currentHash.trim(), callback);
    });
  }
  
  git.exec({ args: `cat-file -t ${hash}` }, function(err, type) {
    if (err) return callback(new Error('Invalid commit hash'));
    
    if (type.trim() !== 'commit') {
      return callback(new Error('Not a commit object'));
    }
    
    git.exec({ args: `show --format="%H %s" -s ${hash}` }, function(err, info) {
      if (err) return callback(err);
      
      const [fullHash, ...messageParts] = info.trim().replace(/"/g, '').split(' ');
      const message = messageParts.join(' ');
      
      callback(null, {
        hash: fullHash,
        shortHash: fullHash.substring(0, 7),
        message: message
      });
    });
  });
}

gulp.task('validate-commit', function(done) {
  validateCommit(process.env.COMMIT_HASH, function(err, commit) {
    if (err) {
      console.error('Commit validation failed:', err.message);
      return done(err);
    }
    
    console.log('✓ Valid commit:', commit.shortHash);
    console.log('Message:', commit.message);
    done();
  });
});