Downloading GitLab repository using API

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

Function downloadGitLabRepo() downloads files from GitLab repository using GitLab API.

Usage

Function has the following parameter:

• options, object. Options, see below.

Function returns:

• DownloadGitLabRepoResult 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.
• project, string. GitLab project ID. You can find it on project page on GitLab website.
• branch, string. Branch, such as "master".
• token, string. GitLab API token. See below.
• uri, string. Optional URI for custom GitLab host, default value is https://gitlab.com/api/v4/projects.

and the following optional properties:

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

Function downloads archive, puts it in target directory, then unpacks it in sub-directory. There are two optional properties that allow you remove outdated files without removing everything. Options do not work if cleanup is enabled because cleanup removes everything.

• cleanupOldFiles, boolean. If true, old zip files in target directory will be removed. Default is false.
• cleanupOldDirectories, boolean. If true, old unpacked archives in target directory will be removed. Default is true.

token

You can get GitLab API token from access tokens page on GitLab.

If you are creating a new token, set scope to "read_api".

Never commit token to a repository or publish it anywhere! Keep it secret. There are many ways to keep token secret, most common is using environmental variables to pass token to script. There are plenty of tutorials available that explain different methods.

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.
• DownloadGitLabRepoResult 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 = "gitlab".
• rootDir, string. Target directory. It is normalized version of target option, without trailing "/" and with "{hash}" replaced with commit hash.
• contentsDir, string. Directory where archive was unpacked.
• hash, string. Last commit hash.

Value is contentsDir always contains rootDir because archives are unpacked in sub-directory of rootDir. For example:

json{
   "downloadType": "gitlab",
   "rootDir": "output/gitlab-test",
   "contentsDir": "output/gitlab-test/iconify-collections-json-4049946",
   "hash": "40499460e21011478a64c1cb1212f3308168462c"
}

Example

download-jam-icons.ts

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

// GITLAB_TOKEN=qwertyuiop node example.js
const token = process.env.GITLAB_TOKEN || '';

(async () => {
   console.log(
       await downloadGitLabRepo({
           target: 'downloads/eos-icons',
           project: '4600360',
           branch: 'master',
           token,
       })
   );
})();