or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

advanced-operations.md branch-operations.md data-operations.md file-operations.md index.md information-status.md remote-operations.md repository-management.md

tile.json

Advanced Operations

Advanced Git operations including tagging, resetting, stashing, submodule management, and executing arbitrary Git commands.

Capabilities

Git Tagging

Creates, lists, or manages Git tags using git tag. Supports signed tags and complex parameter handling.

/**
 * Creates or lists git tags using git tag
 * @param version - Tag version (optional for listing)
 * @param message - Tag message or array of messages (optional, creates lightweight tag if omitted)
 * @param opt - Configuration options (optional)
 * @param cb - Callback function receiving (err, result)
 */
function tag(version?: string, message?: string | string[], opt?: TagOptions, cb?: TagCallback): void;
function tag(version?: string, message?: string | string[], cb?: TagCallback): void;
function tag(version?: string, cb?: TagCallback): void;
function tag(cb?: TagCallback): void;

interface TagOptions extends BaseOptions {
  /** Create signed tag using GPG key */
  signed?: boolean;
  /** Create lightweight tag (no message) */
  lightWeight?: boolean;
}

interface TagCallback {
  (err?: Error, result?: string | string[]): void;
}

Usage Examples:

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

// List all tags
git.tag(function(err, tags) {
  if (err) throw err;
  console.log('Available tags:', tags);
});

// Create lightweight tag
git.tag('v1.0.0', function(err) {
  if (err) throw err;
  console.log('Lightweight tag created');
});

// Create annotated tag with message
git.tag('v1.1.0', 'Release version 1.1.0', function(err) {
  if (err) throw err;
  console.log('Annotated tag created');
});

// Create signed tag
git.tag('v1.2.0', 'Signed release', { signed: true }, function(err) {
  if (err) throw err;
  console.log('Signed tag created');
});

// Create tag with multiple message lines
git.tag('v1.3.0', ['Version 1.3.0', 'Bug fixes and improvements'], function(err) {
  if (err) throw err;
  console.log('Multi-line tag created');
});

// Create lightweight tag explicitly
git.tag('v1.0.1', '', { lightWeight: true }, function(err) {
  if (err) throw err;
  console.log('Lightweight tag created');
});

Git Reset

Resets the repository to a specified commit using git reset. Supports different reset modes.

/**
 * Resets git repository using git reset
 * @param commit - Commit reference (optional, defaults to HEAD)
 * @param opt - Configuration options (optional)
 * @param cb - Callback function (optional if opt provided)
 */
function reset(commit?: string, opt?: ResetOptions, cb?: Callback): void;
function reset(commit?: string, cb?: Callback): void;
function reset(opt?: ResetOptions, cb?: Callback): void;
function reset(cb?: Callback): void;

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

Usage Examples:

// Soft reset to HEAD (keep changes staged)
git.reset('HEAD', { args: '--soft' }, function(err) {
  if (err) throw err;
  console.log('Soft reset completed');
});

// Hard reset to HEAD (discard all changes)
git.reset('HEAD', { args: '--hard' }, function(err) {
  if (err) throw err;
  console.log('Hard reset completed');
});

// Reset to specific commit
git.reset('abc1234', function(err) {
  if (err) throw err;
  console.log('Reset to commit abc1234');
});

// Mixed reset (default - keep changes unstaged)
git.reset('HEAD~1', function(err) {
  if (err) throw err;
  console.log('Reset to previous commit');
});

// Reset specific file
git.reset('HEAD', { args: 'file.txt' }, function(err) {
  if (err) throw err;
  console.log('File reset');
});

Git Stash

Stashes changes using git stash. Includes built-in default message and options.

/**
 * Stashes git changes using git stash
 * @param opt - Configuration options (optional)
 * @param cb - Callback function (optional if opt provided)
 */
function stash(opt?: StashOptions, cb?: Callback): void;
function stash(cb?: Callback): void;

interface StashOptions extends BaseOptions {
  // Inherits: cwd, args, quiet, maxBuffer
  // Default args: 'save --include-untracked "gulp-stash"'
}

Usage Examples:

// Basic stash with default message
git.stash(function(err) {
  if (err) throw err;
  console.log('Changes stashed');
});

// Stash with custom message
git.stash({ args: 'save "Work in progress"' }, function(err) {
  if (err) throw err;
  console.log('Changes stashed with custom message');
});

// Stash including untracked files (default behavior)
git.stash({ args: 'save --include-untracked "Custom stash"' }, function(err) {
  if (err) throw err;
  console.log('All changes stashed');
});

// Pop stash
git.stash({ args: 'pop' }, function(err) {
  if (err) throw err;
  console.log('Stash applied and removed');
});

// List stashes
git.stash({ args: 'list' }, function(err) {
  if (err) throw err;
  console.log('Stash list displayed');
});

// Apply specific stash
git.stash({ args: 'apply stash@{1}' }, function(err) {
  if (err) throw err;
  console.log('Specific stash applied');
});

Execute Git Commands

Executes arbitrary Git commands using git prefix. Useful for commands not covered by specific functions.

/**
 * Executes arbitrary git commands using git prefix
 * @param opt - Configuration options with args property (optional)
 * @param cb - Callback function receiving (err, stdout)
 */
function exec(opt?: ExecOptions, cb?: ExecCallback): void;
function exec(cb?: ExecCallback): void;

interface ExecOptions extends BaseOptions {
  /** Enable/disable logging output (default: !cb) */
  log?: boolean;
}

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

Usage Examples:

// Get commit log
git.exec({ args: 'log --oneline -10' }, function(err, stdout) {
  if (err) throw err;
  console.log('Recent commits:', stdout);
});

// Show file history
git.exec({ args: 'log --follow -- file.txt' }, function(err, stdout) {
  if (err) throw err;
  console.log('File history:', stdout);
});

// Get repository statistics
git.exec({ args: 'shortlog -sn' }, function(err, stdout) {
  if (err) throw err;
  console.log('Contributors:', stdout);
});

// Check configuration
git.exec({ args: 'config --list' }, function(err, stdout) {
  if (err) throw err;
  console.log('Git configuration:', stdout);
});

// Custom command with no logging
git.exec({ args: 'status --porcelain', log: false }, function(err, stdout) {
  if (err) throw err;
  const files = stdout.split('\n').filter(line => line.trim());
  console.log('Changed files:', files.length);
});

Submodule Operations

Add and update Git submodules for managing external repositories.

/**
 * Adds a git submodule using git submodule add
 * @param url - Submodule repository URL (required)
 * @param name - Submodule directory name (optional)
 * @param opt - Configuration options (optional)
 * @param cb - Callback function (optional if opt provided)
 */
function addSubmodule(url: string, name?: string, opt?: SubmoduleOptions, cb?: Callback): void;
function addSubmodule(url: string, name?: string, cb?: Callback): void;
function addSubmodule(url: string, cb?: Callback): void;

/**
 * Updates git submodules using git submodule update
 * @param opt - Configuration options (optional)
 * @param cb - Callback function (optional if opt provided)
 */
function updateSubmodule(opt?: SubmoduleOptions, cb?: Callback): void;
function updateSubmodule(cb?: Callback): void;

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

Usage Examples:

// Add submodule
git.addSubmodule('https://github.com/user/lib.git', 'libs/external', function(err) {
  if (err) throw err;
  console.log('Submodule added');
});

// Add submodule with specific branch
git.addSubmodule('https://github.com/user/lib.git', 'libs/external', {
  args: '-b develop'
}, function(err) {
  if (err) throw err;
  console.log('Submodule added from develop branch');
});

// Update all submodules
git.updateSubmodule(function(err) {
  if (err) throw err;
  console.log('Submodules updated');
});

// Initialize and update submodules
git.updateSubmodule({ args: '--init' }, function(err) {
  if (err) throw err;
  console.log('Submodules initialized and updated');
});

// Update submodules recursively
git.updateSubmodule({ args: '--init --recursive' }, function(err) {
  if (err) throw err;
  console.log('All submodules updated recursively');
});

Common Patterns

Release Workflow with Tags

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

gulp.task('release', function(done) {
  const version = process.env.VERSION;
  if (!version) return done(new Error('VERSION environment variable required'));
  
  // Create release tag
  git.tag(`v${version}`, `Release version ${version}`, function(err) {
    if (err) return done(err);
    
    // Push tag to remote
    git.push('origin', `v${version}`, function(err) {
      if (err) return done(err);
      
      console.log(`Release ${version} tagged and pushed`);
      done();
    });
  });
});

Safe Reset Operations

gulp.task('safe-reset', function(done) {
  // Stash changes first
  git.stash(function(err) {
    if (err && !err.message.includes('No local changes')) {
      return done(err);
    }
    
    // Perform reset
    git.reset('HEAD', { args: '--hard' }, function(err) {
      if (err) return done(err);
      
      console.log('Repository reset to clean state');
      console.log('Previous changes saved in stash');
      done();
    });
  });
});

Repository Cleanup

gulp.task('cleanup', function(done) {
  // Clean untracked files
  git.clean({ args: '-f' }, function(err) {
    if (err) return done(err);
    
    // Reset hard
    git.reset('HEAD', { args: '--hard' }, function(err) {
      if (err) return done(err);
      
      // Update submodules
      git.updateSubmodule({ args: '--init' }, function(err) {
        if (err) return done(err);
        
        console.log('Repository cleaned and reset');
        done();
      });
    });
  });
});

Development Workflow

gulp.task('save-work', function(done) {
  // Stash current work
  git.stash({ args: 'save "Auto-save work in progress"' }, function(err) {
    if (err) return done(err);
    
    // Switch to master
    git.checkout('master', function(err) {
      if (err) return done(err);
      
      // Pull latest changes
      git.pull('origin', 'master', function(err) {
        if (err) return done(err);
        
        console.log('Work saved, switched to updated master');
        done();
      });
    });
  });
});

gulp.task('restore-work', function(done) {
  // Switch back to feature branch
  git.checkout('feature/current-work', function(err) {
    if (err) return done(err);
    
    // Restore stashed work
    git.stash({ args: 'pop' }, function(err) {
      if (err) return done(err);
      
      console.log('Work restored');
      done();
    });
  });
});

Custom Git Operations

function getCommitsSince(since, callback) {
  git.exec({ 
    args: `log --since="${since}" --pretty=format:"%h %s" --no-merges` 
  }, function(err, stdout) {
    if (err) return callback(err);
    
    const commits = stdout.split('\n')
      .filter(line => line.trim())
      .map(line => {
        const [hash, ...messageParts] = line.split(' ');
        return { hash, message: messageParts.join(' ') };
      });
    
    callback(null, commits);
  });
}

gulp.task('changelog', function(done) {
  getCommitsSince('1 week ago', function(err, commits) {
    if (err) return done(err);
    
    console.log('Recent commits:');
    commits.forEach(commit => {
      console.log(`${commit.hash}: ${commit.message}`);
    });
    
    done();
  });
});

Version

Tile

Files