Downloading Git repository

This tutorial is part of package functions documentation in Iconify Tools.

Function downloadGitRepo() creates a shallow clone of Git repository.

Git executable

This function uses Git to clone repository. Make sure Git is installed on your computer.

Usage

Function has the following parameter:

• options, object. Options, see below.

Function returns:

• DownloadGitRepoResult object on success.
• "not_modified" string if repository has not been updated since last run (can be returned only if ifModifiedSince option is set).

In case of error, function might throw an exception, which you can catch using try and catch.

Function is asynchronous. That means you need to handle it as Promise instance, usually by adding await before function call.

Options

Options object has the following mandatory properties:

• target, string. Target directory. If directory is missing, it will be created. Value can contain "{hash}" that will be replaced with latest commit hash.
• remote, string. Git repository, such as "git@github.com:iconify/tools.git".
• branch, string. Branch, such as "master".

and the following optional properties:

• cleanup, boolean. If true, target directory will be emptied before exporting icons. Default is false.
• ifModifiedSince, string|true|DownloadGitRepoResult. If set, function will check if repository has been updated.

ifModifiedSince

Option ifModifiedSince is used when you want to retrieve data only if repository has been updated.

Value can be one of the following:

• Commit hash as string. You can get it from hash property of result of previous run.
• If value is true, function compare hash in remote repository with hash from previously downloaded files in target directory.
• DownloadGitRepoResult value from previous run.

If repository has not been modified, function will return string "not_modified".

If option is not set, function cannot return "not_modified".

Result

Result object has the following properties:

• downloadType = "git".
• contentsDir, string. Directory where repository was cloned to. It is normalized version of target option, without trailing "/" and with "{hash}" replaced with commit hash.
• hash, string. Last commit hash.

Example

boxicons.ts

tsimport { downloadGitRepo } from '@iconify/tools';

(async () => {
   console.log(
       await downloadGitRepo({
           target: 'downloads/boxicons-{hash}',
           remote: 'git@github.com:atisawd/boxicons.git',
           branch: 'master',
           ifModifiedSince: true,
           log: true,
       })
   );
})();