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

file-operations.mddocs/

File Operations

Stream-based operations for staging, committing, and manipulating files in Git repositories. These functions integrate with Gulp's file streaming system and return Transform streams that can be piped together.

Capabilities

Add Files

Stages files for commit using git add. Processes vinyl files through a Transform stream.

/**
 * Stages files for commit using git add
 * @param opt - Configuration options
 * @returns Transform stream that processes vinyl files
 */
function add(opt?: AddOptions): Transform;

interface AddOptions extends BaseOptions {
  /** Maximum files to process at once (default: Infinity) - useful for Windows command line length limits */
  maxFiles?: number;
}

Usage Examples:

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

// Add all files in src directory
gulp.task('add', function() {
  return gulp.src('./src/*')
    .pipe(git.add());
});

// Add with custom options
gulp.task('add-force', function() {
  return gulp.src('./src/*')
    .pipe(git.add({ args: '-f' }));
});

// Add with file limit for Windows
gulp.task('add-limited', function() {
  return gulp.src('./src/*')
    .pipe(git.add({ maxFiles: 8 }));
});

Commit Changes

Creates Git commits with support for single or multiple commit messages. Supports function-based messages for delayed execution.

/**
 * Creates git commits with support for multiline messages
 * @param message - Commit message as string, array of strings, or function returning string
 * @param opt - Configuration options
 * @returns Transform stream that processes files and commits them
 */
function commit(message: string | string[] | (() => string), opt?: CommitOptions): Transform;

interface CommitOptions extends BaseOptions {
  /** Enable multiline message handling with -F flag */
  multiline?: boolean;
  /** Allow commits without message requirement */
  disableMessageRequirement?: boolean;  
  /** Don't append file paths to commit command */
  disableAppendPaths?: boolean;
  /** Emit 'data' events during commit execution for progress tracking */
  emitData?: boolean;
}

Usage Examples:

// Basic commit
gulp.task('commit', function() {
  return gulp.src('./src/*')
    .pipe(git.commit('Initial commit'));
});

// Commit with multiple messages
gulp.task('commit-multi', function() {
  return gulp.src('./src/*')
    .pipe(git.commit(['Initial commit', 'Added new features']));
});

// Commit with function-based message
gulp.task('commit-dynamic', function() {
  return gulp.src('./src/*')
    .pipe(git.commit(() => `Version ${pkg.version}`));
});

// Commit with amend
gulp.task('commit-amend', function() {
  return gulp.src('./src/*')
    .pipe(git.commit('Updated commit', { args: '--amend' }));
});

// Commit with progress tracking
gulp.task('commit-progress', function() {
  return gulp.src('./src/*')
    .pipe(git.commit('Long commit', { emitData: true }))
    .on('data', function(data) {
      console.log('Commit progress:', data);
    });
});

// Commit using raw arguments without message
gulp.task('commit-raw', function() {
  return gulp.src('./src/*')
    .pipe(git.commit(undefined, {
      args: '-m "Raw commit"',
      disableMessageRequirement: true
    }));
});

Remove Files

Removes files from Git using git rm. Collects all files and removes them in a single batch operation.

/**
 * Removes files from git using git rm command
 * @param opt - Configuration options
 * @returns Transform stream that collects and removes files
 */
function rm(opt?: RmOptions): Transform;

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

Usage Examples:

// Remove files
gulp.task('remove', function() {
  return gulp.src('./temp/*')
    .pipe(git.rm());
});

// Force remove with custom args
gulp.task('remove-force', function() {
  return gulp.src('./temp/*')
    .pipe(git.rm({ args: '-f' }));
});

Checkout Files

Checkout (reset) specific files using git checkout. Useful for reverting files to their committed state.

/**
 * Checkout files using git checkout command
 * @param opt - Configuration options
 * @returns Transform stream that processes vinyl files
 */
function checkoutFiles(opt?: CheckoutFilesOptions): Transform;

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

Usage Examples:

// Checkout (revert) files
gulp.task('revert', function() {
  return gulp.src('./src/*')
    .pipe(git.checkoutFiles());
});

// Checkout from specific commit
gulp.task('revert-commit', function() {
  return gulp.src('./src/*')
    .pipe(git.checkoutFiles({ args: 'HEAD~1' }));
});

Common Patterns

Chaining File Operations

gulp.task('commit-flow', function() {
  return gulp.src('./src/*')
    .pipe(git.add())
    .pipe(git.commit('Automated commit'));
});

Error Handling in Streams

gulp.task('safe-commit', function() {
  return gulp.src('./src/*')
    .pipe(git.add())
    .pipe(git.commit('Safe commit'))
    .on('error', function(err) {
      console.error('Commit failed:', err.message);
      this.emit('end');
    });
});

Working with Large File Sets

// For Windows - avoid command line length limits
gulp.task('add-many', function() {
  return gulp.src('./src/**/*')
    .pipe(git.add({ 
      maxFiles: 8,
      maxBuffer: 1024 * 1024 // 1MB buffer
    }));
});