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

remote-operations.mddocs/

Remote Operations

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();
      }
    });
  });
});