DOCSEARCHbyAlgolia
Submit Docs

giget

repository·main·Indexed 20 days ago

https://github.com/unjs/giget

A lightweight, zero-dependency tool for downloading templates and git repositories. It supports multiple providers including GitHub, GitLab, Bitbucket, and Sourcehut, as well as custom registries and sparse checkouts for subdirectories. giget can be used via a CLI or programmatically through the downloadTemplate() function.

Tokens
5.4K
Snippets
19
Records
24
Agent score
73%

What's inside giget

  1. Use a custom template registry

    main

    A custom registry is an HTTP endpoint that responds to /:template.json requests. The JSON response must include:

    • name: (required) Template name.
    • tar: (required) Link to the tarball download.
    • defaultDir: (optional) Default directory.
    • url: (optional) Webpage URL.
    • subdir: (optional) Subdirectory inside the tar.
    • headers: (optional) Custom headers for the download.

    You can register a custom registry using the registryProvider utility:

    import { downloadTemplate, registryProvider } from "giget";

const themes = registryProvider("https://raw.githubusercontent.com/unjs/giget/main/templates");

await downloadTemplate("themes:test", {
  providers: { themes },
});
    import { registryProvider } from "giget";

const themes = registryProvider("https://raw.githubusercontent.com/unjs/giget/main/templates");

const { source, dir } = await downloadTemplate("themes:test", {
  providers: { themes },
});

  2. Use the Git Clone Provider for local or private repos

    main

    The git: provider uses the local git command instead of HTTP tarballs. This is ideal for private servers or local repositories. It uses sparse checkout to avoid downloading the entire history/repository when a subdirectory is specified.

    Syntax Examples:

    • git:unjs/template — HTTPS clone (defaults to GitHub).
    • git:unjs/template#v2 — Specific branch or tag.
    • git:unjs/template#main:src — Subdirectory via sparse checkout.
    • git:git@github.com:unjs/template — Explicit SSH.
    • git:./path/to/local/repo — Local repository.
    • gitlab+git:org/repo — GitLab host shorthand.

    Environment Variables:

    • GIGET_GIT_HOST: Set the default HTTPS host (default: https://github.com/).
    git:unjs/template                    # HTTPS clone
git:unjs/template#v2                 # Specific branch or tag
git:unjs/template#main:src           # Subdirectory (sparse checkout)
git:git@github.com:unjs/template     # Explicit SSH
git:./path/to/local/repo             # Local repository
gh+git:unjs/template                 # Host shorthand (github.com)
gitlab+git:org/repo                  # Host shorthand (gitlab.com)

  3. Authenticate with private repositories

    main

    To download private templates, you must provide an authorization token. This token is sent as a Authorization: Bearer <token> header.

    Methods of providing authentication:

    1. CLI: Use the --auth <token> flag.
    2. Programmatic: Use the auth option in downloadTemplate.
    3. Environment Variable: Set GIGET_AUTH in your environment.

    GitHub Actions Example:

    - name: Install packages
  run: npm ci
  env:
    GIGET_AUTH: ${{ secrets.GIGET_AUTH }}

    Note: For GitHub Fine-grained access tokens, ensure the token has Contents and Metadata permissions.

  4. Download templates programmatically with downloadTemplate()

    main

    For integration into your own tools, import downloadTemplate to download templates via code. It returns a promise that resolves to an object containing the destination dir and the normalized source.

    import { downloadTemplate } from "giget";

const { source, dir } = await downloadTemplate("github:unjs/template", {
  dir: "my-project",
  install: true
});

    Options

    • source: String in format [provider]:repo[/subpath][#ref]. Use :: for subdirectories in complex paths (e.g., gitlab:group/subgroup/repo::subdir).
    • dir: Destination directory. Defaults to user-name relative to CWD.
    • provider: github, gitlab, bitbucket, sourcehut, or git. Defaults to github.
    • force: Boolean to overwrite existing directory.
    • forceClean: Boolean to clean the directory before cloning.
    • offline: Boolean to skip cache and force download.
    • preferOffline: Boolean to use cache if available.
    • registry: URL string for a custom registry or false to disable.
    • auth: Authorization token (can be set via GIGET_AUTH).
    • ignore: An array of glob patterns (e.g., ["*.md"]) or a callback function (path) => boolean to skip files.
    import { downloadTemplate } from "giget";

const { source, dir } = await downloadTemplate("github:unjs/template");

  5. Create custom template providers

    main

    You can extend giget by defining custom TemplateProvider functions. These functions receive the input (the version or variant) and an auth token, returning an object that describes how to fetch the template.

    import type { TemplateProvider } from "giget";
import { downloadTemplate } from "giget";

const rainbow: TemplateProvider = async (input, { auth }) => {
  return {
    name: "rainbow",
    version: input,
    headers: { authorization: auth },
    url: `https://rainbow.template/?variant=${input}`,
    tar: `https://rainbow.template/dl/rainbow.${input}.tar.gz`,
  };
};

await downloadTemplate("rainbow:one", {
  providers: { rainbow },
});

    Note: The tar property can also be an async function that returns a Readable or ReadableStream (e.g., from a fetch response body).

    import type { TemplateProvider } from "giget";

const rainbow: TemplateProvider = async (input, { auth }) => {
  return {
    name: "rainbow",
    version: input,
    headers: { authorization: auth },
    url: `https://rainbow.template/?variant=${input}`,
    tar: `https://rainbow.template/dl/rainbow.${input}.tar.gz`,
  };
};

const { source, dir } = await downloadTemplate("rainbow:one", {
  providers: { rainbow },
});

  6. Configure GitHub Enterprise via environment variables

    main

    When using the github provider, you can specify a custom GitHub Enterprise URL by setting the GIGET_GITHUB_URL environment variable. If not set, it defaults to https://api.github.com.

    export const github: TemplateProvider = (input, options) => {
  // ...
  const githubAPIURL = process.env.GIGET_GITHUB_URL || "https://api.github.com";
  // ...
};

  7. Configure GitLab Enterprise via environment variables

    main

    When using the gitlab provider, you can specify a custom GitLab instance URL by setting the GIGET_GITLAB_URL environment variable. If not set, it defaults to https://gitlab.com.

    export const gitlab: TemplateProvider = (input, options) => {
  // ...
  const gitlab = process.env.GIGET_GITLAB_URL || "https://gitlab.com";
  // ...
};

  8. Use the giget CLI

    main

    You can use giget via npx to download templates or git repositories directly from your terminal. The syntax is:

    npx giget@latest <template> [<dir>] [...options]

    Arguments

    • template: The template name or a URI (e.g., gh:user/repo, gitlab:group/project, or a direct URL).
    • dir: The destination path where the template should be extracted.

    Common Options

    • --force: Overwrite the destination directory if it already exists.
    • --force-clean: Recursively remove the destination directory before cloning.
    • --install: Automatically install dependencies after cloning using unjs/nypm.
    • --registry <url>: Use a custom registry URL (can be set via GIGET_REGISTRY).
    • --auth <token>: Provide an authorization token (can be set via GIGET_AUTH).
    • --ignore <patterns>: Comma-separated glob patterns to skip during extraction (e.g., --ignore pnpm-lock.yaml,*.md).
    • --prefer-offline: Use the local cache if available, otherwise download.

  9. Filter extracted files using the ignore option

    main

    You can prevent specific files from being extracted by using the ignore option in downloadTemplate. This is useful for skipping lockfiles, local configuration, or large assets.

    Supported formats:

    1. Glob Patterns: An array of strings compatible with Node.js path.matchesGlob (requires Node.js v22.5.0, v20.17.0 or later).
    2. Callback Function: A function that receives the relative path of each entry and returns true to skip it or false to keep it.

    Note: Glob pattern support requires modern Node.js versions.

    // Using glob patterns (Node.js v22.5.0+ / v20.17.0+)
await downloadTemplate('github:user/repo', {
  ignore: ['package-lock.json', 'node_modules/**']
});

// Using a callback function
await downloadTemplate('github:user/repo', {
  ignore: (path) => path.endsWith('.log') || path.includes('temp/')
});

  10. Use the git TemplateProvider

    main

    The git object is a TemplateProvider implementation that allows fetching templates from Git repositories. It returns an object containing the provider's name, a version (which includes the subdirectory in the cache key to ensure uniqueness), and a tar function to retrieve the content.

    To use it, call git(input, options). The tar function can accept an auth option to provide a token for authenticated clones.

    import { git } from 'giget';

const provider = git('github:unjs/giget#main');
const stream = await provider.tar({ auth: 'YOUR_TOKEN' });

  11. Configure downloadTemplate options

    main

    The DownloadTemplateOptions object allows you to fine-tune the download and extraction process. Key options include:

    • dir: The destination directory for the extracted template. Defaults to the template's defaultDir.
    • provider: Explicitly specify a provider name (e.g., 'github', 'gitlab', 'git').
    • registry: A string URL for a custom registry, or false to disable registry lookups.
    • auth: Authentication token (passed as a Bearer token in headers or used by providers).
    • install: A boolean to trigger dependency installation, or an object of InstallOptions to pass directly to nypm.
    • force: If true, allows overwriting an existing directory. If false (default), throws an error if the destination is not empty.
    • forceClean: If true, deletes the destination directory before extraction.
    • offline / preferOffline: Controls whether to use cached versions of the template.
    • ignore: A way to skip specific files during extraction using glob patterns or a callback function.
    • silent: If true, suppresses output during dependency installation.
    • cwd: The current working directory for the operation.
    await downloadTemplate('github:user/repo', {
  dir: './my-project',
  install: { silent: true }, // Pass options to nypm
  ignore: ['pnpm-lock.yaml', '*.log'], // Ignore via glob patterns
  force: true
});

  12. Authenticate with providers using the auth option

    main
    Most built-in providers (GitHub, GitLab, Bitbucket, Sourcehut, and HTTP) support authentication. You can pass an authentication token via the options.auth property. This token is typically sent as a Bearer token in the Authorization header.