cloneRepository

Clone a remote repository.

This will use the options configured so far to clone the specified URL into the specified local path.

Signature

function cloneRepository(
  url: string,
  path: string,
  options?: RepositoryCloneOptions | null,
  signal?: AbortSignal | null
): Promise<Repository>;

Parameters

• urlrequired · string
  

  Remote URL for repository.

• pathrequired · string
  

  Local path to clone repository.

• optionsnull | RepositoryCloneOptions
  

  Clone options for repository.

  • bareboolean
    

    Indicate whether the repository will be cloned as a bare repository or not.

  • branchstring
    

    Specify the name of the branch to check out after the clone. If not specified, the remote's default branch will be used.

  • fetchFetchOptions
    

    Options which can be specified to various fetch operations.

    • credentialCredential
      

      A interface to represent git credentials in libgit2.

    • customHeadersstring[]
      

      Set extra headers for this fetch operation.

    • depthnumber
      

      Set fetch depth, a value less or equal to 0 is interpreted as pull everything (effectively the same as not declaring a limit depth).

    • downloadTagsAutotagOption
      

      Set how to behave regarding tags on the remote, such as auto-downloading tags for objects we're downloading or downloading all of them. The default is to auto-follow tags.

      - Unspecified : Use the setting from the remote's configuration
      - Auto : Ask the server for tags pointing to objects we're already downloading
      - None : Don't ask for any tags beyond the refspecs
      - All : Ask for all the tags

    • followRedirectsRemoteRedirect
      

      Set remote redirection settings; whether redirects to another host are permitted. By default, git will follow a redirect on the initial request (/info/refs), but not subsequent requests.

      - None : Do not follow any off-site redirects at any stage of the fetch or push.
      - Initial : Allow off-site redirects only upon the initial request. This is the default.
      - All : Allow redirects at any stage in the fetch or push.

    • proxyProxyOptions
      

      Set the proxy options to use for the fetch operation.

      • autoboolean
        

        Try to auto-detect the proxy from the git configuration. Note that this will override url specified before.

      • urlstring
        

        Specify the exact URL of the proxy to use. Note that this will override auto specified before.

    • pruneFetchPrune
      

      Set whether to perform a prune after the fetch.

      - Unspecified : Use the setting from the configuration.
      - On : Force pruning on.
      - Off : Force pruning off

  • recursiveboolean
    

    Clone a remote repository, initialize and update its submodules recursively. This is similar to git clone --recursive.

• signalnull | AbortSignal
  

  Abort signal.

Returns

• Promise<Repository>
  

  Repository instance

Examples

Clone repository using https:// protocol.

import { cloneRepository } from 'es-git';

const repo = await cloneRepository(
  'https://github.com/toss/es-git',
  '/path/to/clone',
);

Clone repository using git:// protocol.

import { cloneRepository } from 'es-git';

const repo = await cloneRepository(
  'git@github.com:toss/es-git',
  '/path/to/clone',
);

Clone repository with authentication.

import { cloneRepository } from 'es-git';

// Authenticate using ssh-agent
const repo = await cloneRepository('git@github.com:toss/es-git', '.', {
  fetch: {
    credential: {
      type: 'SSHKeyFromAgent',
    },
  },
});