@es-git/fetch-mixin

fetch-mixin

This is part of the ES-Git project.

Install

npm install --save @es-git/fetch-mixin

Usage

This mixin adds the ability to fetch remote branches to a local repository, using the smart HTTP transport protocol. This works well with online git hosts, like GitHub, GitLab, BitBucket and others.

import fetchMixin from '@es-git/fetch-mixin';
import MemoryRepo from '@es-git/memory-repo';

const Repo = mix(MemoryRepo)
            .with(fetchMixin, fetch);

const repo = new Repo();

await repo.fetch('https://github.com/es-git/test-pull.git');

When mixing this module in with a repo you need to pass fetch in as a second parameter. fetch is available in all modern browsers and node-fetch can be used server-side.

The simplest way to fetch is to provide a url, in which case it will fetch all remote branches (refs/heads/*) and store them locally (refs/remotes/origin/*).

You can change this by supplying one or more refspecs, in the form what/to/fetch:where/to/save/it. If the last segment is a * wildcard, then it will match multiple refs.

fetch will return a promise that resolves when the fetch has completed. For progress report during fetch supply a progress function in the options object.

You can optionally decide to do a shallow fetch by supplying a depth number in the options object. For example, setting depth to 1 will fetch only the last commit. To later fetch the rest of the history, set unshallow to true. If you only want to later fetch (for example) the last 10 commits, set unshallow to true and depth to 10.

If the fetch succeeds the result will be a list of fetched refs. Note that branches (refs) that are the same on the client and server will not be fetched but will be part of the result. The name is the branch that has been fetched (for example refs/remotes/origin/master), hash contains the hash it now points to while oldHash, if present, is the hash that it used to point to. If the branch didn't exist locally before the fetch, then oldHash is undefined. If there was nothing to fetch for the branch, then hash and oldHash will contain the same value.

lsRemote calls the remote endpoint and resolves to a list of references that the remote end knows about.

Interfaces

IPushRepo

interface IFetchRepo {
  fetch(url : string, refspec? : string | string[], options? : FetchOptions) : Promise<RefChange[]>
  lsRemote(url : string) : Promise<Ref[]>
}

interface FetchOptions {
  readonly depth? : number,
  readonly unshallow? : boolean,
  readonly progress? : (message : string) => void
}

interface RefChange {
  readonly name: string;
  readonly oldHash?: string;
  readonly hash: string;
}

interface Ref {
  readonly name: string;
  readonly hash: Hash;
}