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

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Remote Operations

Name: tessl/npm-gulp-git
Author: tessl

Functions for managing remote repositories, pushing, pulling, and fetching changes. All functions are callback-based and support flexible parameter handling for different use cases.

Capabilities

Add Remote

Adds a remote repository URL using git remote add.

/**
 * Adds a git remote repository using git remote add
 * @param remote - Remote name (defaults to 'origin')
 * @param url - Remote repository URL (required)
 * @param opt - Configuration options (optional)
 * @param cb - Callback function (optional if opt provided)
 */
function addRemote(remote: string, url: string, opt?: RemoteOptions, cb?: Callback): void;
function addRemote(remote: string, url: string, cb?: Callback): void;

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

Usage Examples:

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

// Add origin remote
git.addRemote('origin', 'https://github.com/user/repo.git', function(err) {
  if (err) throw err;
  console.log('Origin remote added');
});

// Add upstream remote
git.addRemote('upstream', 'https://github.com/original/repo.git', function(err) {
  if (err) throw err;
  console.log('Upstream remote added');
});

// Add remote with custom fetch refspec
git.addRemote('origin', 'https://github.com/user/repo.git', {
  args: '--fetch'
}, function(err) {
  if (err) throw err;
  console.log('Remote added with fetch');
});

Remove Remote

Removes a remote repository using git remote remove.

/**
 * Removes a git remote using git remote remove
 * @param remote - Remote name to remove (required)
 * @param opt - Configuration options (optional)
 * @param cb - Callback function (optional if opt provided)
 */
function removeRemote(remote: string, opt?: RemoteOptions, cb?: Callback): void;
function removeRemote(remote: string, cb?: Callback): void;

Usage Examples:

// Remove origin remote
git.removeRemote('origin', function(err) {
  if (err) throw err;
  console.log('Origin remote removed');
});

// Remove upstream remote
git.removeRemote('upstream', function(err) {
  if (err) throw err;
  console.log('Upstream remote removed');
});

Push Changes

Pushes changes to remote repository using git push. Automatically detects current branch if not specified.

/**
 * Pushes changes to remote repository using git push
 * @param remote - Remote name (defaults to 'origin')
 * @param branch - Branch name or array of branches (auto-detected if not provided)
 * @param opt - Configuration options (optional)
 * @param cb - Callback function (optional if opt provided)
 */
function push(remote?: string, branch?: string | string[], opt?: RemoteOptions, cb?: Callback): void;
function push(remote?: string, branch?: string | string[], cb?: Callback): void;
function push(remote?: string, cb?: Callback): void;
function push(cb?: Callback): void;

Usage Examples:

// Basic push to origin/current branch
git.push(function(err) {
  if (err) throw err;
  console.log('Pushed to origin');
});

// Push to specific remote and branch
git.push('origin', 'master', function(err) {
  if (err) throw err;
  console.log('Pushed master to origin');
});

// Push multiple branches
git.push('origin', ['master', 'develop'], function(err) {
  if (err) throw err;
  console.log('Pushed multiple branches');
});

// Push with tags
git.push('origin', 'master', { args: '--tags' }, function(err) {
  if (err) throw err;
  console.log('Pushed with tags');
});

// Force push
git.push('origin', 'feature/rewrite', { args: '--force' }, function(err) {
  if (err) throw err;
  console.log('Force pushed feature branch');
});

// Push and set upstream
git.push('origin', 'new-feature', { args: '--set-upstream' }, function(err) {
  if (err) throw err;
  console.log('Pushed and set upstream');
});

Pull Changes

Pulls changes from remote repository using git pull. Supports multiple branches and flexible parameters.

/**
 * Pulls changes from remote repository using git pull
 * @param remote - Remote name (optional)
 * @param branch - Branch name or array of branches (optional)
 * @param opt - Configuration options (optional)
 * @param cb - Callback function (optional if opt provided)
 */
function pull(remote?: string, branch?: string | string[], opt?: RemoteOptions, cb?: Callback): void;
function pull(remote?: string, branch?: string | string[], cb?: Callback): void;
function pull(remote?: string, cb?: Callback): void;
function pull(cb?: Callback): void;

Usage Examples:

// Basic pull from current upstream
git.pull(function(err) {
  if (err) throw err;
  console.log('Pulled latest changes');
});

// Pull from specific remote
git.pull('upstream', function(err) {
  if (err) throw err;
  console.log('Pulled from upstream');
});

// Pull specific branch
git.pull('origin', 'master', function(err) {
  if (err) throw err;
  console.log('Pulled master from origin');
});

// Pull multiple branches
git.pull('origin', ['master', 'develop'], function(err) {
  if (err) throw err;
  console.log('Pulled multiple branches');
});

// Pull with rebase
git.pull('origin', 'master', { args: '--rebase' }, function(err) {
  if (err) throw err;
  console.log('Pulled and rebased');
});

// Pull with merge strategy
git.pull('origin', 'master', { args: '--strategy=ours' }, function(err) {
  if (err) throw err;
  console.log('Pulled with merge strategy');
});

Fetch Changes

Fetches refs and objects from remote repository using git fetch. Supports fetching from all remotes.

/**
 * Fetches from remote repository using git fetch
 * @param remote - Remote name (defaults to 'origin', or empty for --all)
 * @param branch - Branch name (optional)
 * @param opt - Configuration options (optional)
 * @param cb - Callback function (optional if opt provided)
 */
function fetch(remote?: string, branch?: string, opt?: RemoteOptions, cb?: Callback): void;
function fetch(remote?: string, branch?: string, cb?: Callback): void;
function fetch(remote?: string, cb?: Callback): void;
function fetch(cb?: Callback): void;

Usage Examples:

// Fetch from origin
git.fetch('origin', function(err) {
  if (err) throw err;
  console.log('Fetched from origin');
});

// Fetch specific branch
git.fetch('origin', 'master', function(err) {
  if (err) throw err;
  console.log('Fetched master from origin');
});

// Fetch from all remotes
git.fetch('', '', { args: '--all' }, function(err) {
  if (err) throw err;
  console.log('Fetched from all remotes');
});

// Fetch with prune (remove deleted remote branches)
git.fetch('origin', '', { args: '--prune' }, function(err) {
  if (err) throw err;
  console.log('Fetched with prune');
});

// Fetch tags
git.fetch('origin', '', { args: '--tags' }, function(err) {
  if (err) throw err;
  console.log('Fetched tags');
});

Common Patterns

Remote Setup Workflow

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

gulp.task('setup-remotes', function(done) {
  // Add origin
  git.addRemote('origin', 'https://github.com/user/fork.git', function(err) {
    if (err) return done(err);
    
    // Add upstream
    git.addRemote('upstream', 'https://github.com/original/repo.git', function(err) {
      if (err) return done(err);
      
      console.log('Remotes configured');
      done();
    });
  });
});

Sync with Upstream

gulp.task('sync-upstream', function(done) {
  // Fetch from upstream
  git.fetch('upstream', function(err) {
    if (err) return done(err);
    
    // Checkout master
    git.checkout('master', function(err) {
      if (err) return done(err);
      
      // Merge upstream/master
      git.merge('upstream/master', function(err) {
        if (err) return done(err);
        
        // Push to origin
        git.push('origin', 'master', function(err) {
          if (err) return done(err);
          
          console.log('Synced with upstream');
          done();
        });
      });
    });
  });
});

Release Workflow

gulp.task('release', function(done) {
  const version = process.env.VERSION;
  if (!version) return done(new Error('VERSION required'));
  
  // Create and push tag
  git.tag(version, `Release ${version}`, function(err) {
    if (err) return done(err);
    
    // Push changes
    git.push('origin', 'master', function(err) {
      if (err) return done(err);
      
      // Push tags
      git.push('origin', 'master', { args: '--tags' }, function(err) {
        if (err) return done(err);
        
        console.log(`Release ${version} pushed`);
        done();
      });
    });
  });
});

Safe Push with Checks

function safePush(remote, branch, options, callback) {
  if (typeof options === 'function') {
    callback = options;
    options = {};
  }
  
  // Check if branch is up to date first
  git.fetch(remote, branch, function(err) {
    if (err) return callback(err);
    
    // Check for divergence (this would need custom exec)
    git.exec({ args: `log ${remote}/${branch}..HEAD --oneline` }, function(err, stdout) {
      if (err) return callback(err);
      
      if (!stdout.trim()) {
        return callback(new Error('No changes to push'));
      }
      
      // Proceed with push
      git.push(remote, branch, options, callback);
    });
  });
}

Error Handling for Remote Operations

function handleRemoteError(err, operation) {
  if (!err) return false;
  
  const message = err.message.toLowerCase();
  
  if (message.includes('permission denied')) {
    console.error('Authentication failed. Check your credentials.');
    console.log('Try: git config --global credential.helper store');
    return true;
  }
  
  if (message.includes('non-fast-forward')) {
    console.error('Push rejected. Pull latest changes first:');
    console.log('git pull origin master');
    return true;
  }
  
  if (message.includes('repository not found')) {
    console.error('Repository not found. Check the URL and permissions.');
    return true;
  }
  
  if (message.includes('network')) {
    console.error('Network error. Check your connection.');
    return true;
  }
  
  return true; // Propagate other errors
}

gulp.task('safe-push', function(done) {
  git.push('origin', 'master', function(err) {
    if (handleRemoteError(err, 'push')) {
      return done(err);
    }
    console.log('Push completed successfully');
    done();
  });
});

Batch Remote Operations

gulp.task('sync-all', function(done) {
  const remotes = ['origin', 'upstream', 'backup'];
  let completed = 0;
  
  remotes.forEach(function(remote) {
    git.fetch(remote, function(err) {
      if (err) {
        console.warn(`Failed to fetch from ${remote}:`, err.message);
      } else {
        console.log(`Fetched from ${remote}`);
      }
      
      completed++;
      if (completed === remotes.length) {
        console.log('All remotes synced');
        done();
      }
    });
  });
});