CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-gulp-git

Git plugin for gulp providing comprehensive git command integration for build workflows

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

branch-operations.mddocs/

Branch Operations

Operations for creating, switching, and managing Git branches and merging. All functions are callback-based and execute Git commands directly.

Capabilities

Create Branch

Creates a new Git branch using git branch. Does not switch to the new branch.

/**
 * Creates a new git branch using git branch
 * @param branch - Branch name (required)
 * @param opt - Configuration options (optional)
 * @param cb - Callback function (optional if opt provided)
 */
function branch(branch: string, opt?: BranchOptions, cb?: Callback): void;
function branch(branch: string, cb?: Callback): void;

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

Usage Examples:

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

// Create new branch
git.branch('feature/new-feature', function(err) {
  if (err) throw err;
  console.log('Branch created');
});

// Create branch from specific commit
git.branch('hotfix/bug-fix', { args: 'abc123' }, function(err) {
  if (err) throw err;
  console.log('Branch created from commit abc123');
});

// Create branch with verbose output
git.branch('develop', { args: '-v' }, function(err) {
  if (err) throw err;
  console.log('Branch created with verbose output');
});

Checkout Branch

Switches to a different branch or creates and switches to a new branch using git checkout.

/**
 * Checkout a git branch using git checkout
 * @param branch - Branch name (required)
 * @param opt - Configuration options (optional)
 * @param cb - Callback function (optional if opt provided)
 */
function checkout(branch: string, opt?: BranchOptions, cb?: Callback): void;
function checkout(branch: string, cb?: Callback): void;

Usage Examples:

// Switch to existing branch
git.checkout('develop', function(err) {
  if (err) throw err;
  console.log('Switched to develop branch');
});

// Create and switch to new branch
git.checkout('feature/user-auth', { args: '-b' }, function(err) {
  if (err) throw err;
  console.log('Created and switched to feature/user-auth');
});

// Checkout specific commit (detached HEAD)
git.checkout('abc1234', function(err) {
  if (err) throw err;
  console.log('Checked out commit abc1234');
});

// Force checkout (discard local changes)
git.checkout('master', { args: '-f' }, function(err) {
  if (err) throw err;
  console.log('Force checked out master');
});

Merge Branch

Merges a branch into the current branch using git merge.

/**
 * Merges a git branch using git merge
 * @param branch - Source branch name to merge (required)
 * @param opt - Configuration options (optional)
 * @param cb - Callback function (optional if opt provided)
 */
function merge(branch: string, opt?: BranchOptions, cb?: Callback): void;
function merge(branch: string, cb?: Callback): void;

Usage Examples:

// Basic merge
git.merge('feature/new-feature', function(err) {
  if (err) throw err;
  console.log('Branch merged successfully');
});

// Merge with no fast-forward
git.merge('develop', { args: '--no-ff' }, function(err) {
  if (err) throw err;
  console.log('Merge completed with merge commit');
});

// Squash merge
git.merge('feature/cleanup', { args: '--squash' }, function(err) {
  if (err) throw err;
  console.log('Squash merge completed');
});

// Merge with custom message
git.merge('hotfix/security', { args: '-m "Security hotfix merge"' }, function(err) {
  if (err) throw err;
  console.log('Merge completed with custom message');
});

Common Patterns

Feature Branch Workflow

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

gulp.task('create-feature', function(done) {
  const featureName = process.env.FEATURE_NAME || 'new-feature';
  
  // Create and switch to feature branch
  git.checkout(`feature/${featureName}`, { args: '-b' }, function(err) {
    if (err) return done(err);
    console.log(`Feature branch feature/${featureName} created`);
    done();
  });
});

gulp.task('finish-feature', function(done) {
  const featureName = process.env.FEATURE_NAME || 'new-feature';
  
  // Switch to develop
  git.checkout('develop', function(err) {
    if (err) return done(err);
    
    // Merge feature branch
    git.merge(`feature/${featureName}`, { args: '--no-ff' }, function(err) {
      if (err) return done(err);
      
      console.log(`Feature ${featureName} merged to develop`);
      done();
    });
  });
});

Release Branch Workflow

gulp.task('create-release', function(done) {
  const version = process.env.VERSION || '1.0.0';
  
  git.checkout('develop', function(err) {
    if (err) return done(err);
    
    // Create release branch from develop
    git.checkout(`release/${version}`, { args: '-b' }, function(err) {
      if (err) return done(err);
      
      console.log(`Release branch release/${version} created`);
      done();
    });
  });
});

gulp.task('finish-release', function(done) {
  const version = process.env.VERSION || '1.0.0';
  
  // Merge to master
  git.checkout('master', function(err) {
    if (err) return done(err);
    
    git.merge(`release/${version}`, function(err) {
      if (err) return done(err);
      
      // Merge back to develop
      git.checkout('develop', function(err) {
        if (err) return done(err);
        
        git.merge(`release/${version}`, function(err) {
          if (err) return done(err);
          
          console.log(`Release ${version} finished`);
          done();
        });
      });
    });
  });
});

Branch Cleanup

gulp.task('cleanup-branches', function(done) {
  // This would typically be done with git branch -d
  // but requires custom exec command
  git.exec({ args: 'branch -d feature/old-feature' }, function(err, stdout) {
    if (err) {
      console.log('Branch may not be fully merged:', err.message);
      return done();
    }
    console.log('Branch deleted:', stdout);
    done();
  });
});

Safe Branch Operations

function safeBranchOperation(operation, branch, options, callback) {
  if (typeof options === 'function') {
    callback = options;
    options = {};
  }
  
  // Check if branch exists first for checkout operations
  if (operation === 'checkout') {
    git.exec({ args: `show-ref --verify --quiet refs/heads/${branch}` }, function(err) {
      if (err) {
        // Branch doesn't exist, create it
        options.args = (options.args || '') + ' -b';
      }
      git[operation](branch, options, callback);
    });
  } else {
    git[operation](branch, options, callback);
  }
}

// Usage
safeBranchOperation('checkout', 'feature/maybe-exists', function(err) {
  if (err) throw err;
  console.log('Branch checked out (created if needed)');
});

Error Handling for Branch Operations

function handleBranchError(err, operation, branch) {
  if (!err) return false;
  
  const message = err.message.toLowerCase();
  
  if (message.includes('already exists') && operation === 'branch') {
    console.log(`Branch ${branch} already exists, continuing...`);
    return false; // Don't propagate error
  }
  
  if (message.includes('not found') && operation === 'checkout') {
    console.error(`Branch ${branch} not found. Available branches:`);
    git.exec({ args: 'branch -a' }, function(err, stdout) {
      if (!err) console.log(stdout);
    });
  }
  
  return true; // Propagate error
}

gulp.task('safe-checkout', function(done) {
  git.checkout('maybe-missing-branch', function(err) {
    if (handleBranchError(err, 'checkout', 'maybe-missing-branch')) {
      return done(err);
    }
    console.log('Checkout completed');
    done();
  });
});

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