giget

愉快地下载模板和 Git 仓库！

功能特性

✨ 开箱即用，支持主流 Git 提供商（GitHub、GitLab、Bitbucket、Sourcehut）。

✨ 内置和自定义模板注册表。

✨ 使用 tarball gzip 快速克隆，不依赖本地 git 和 tar。

✨ 支持磁盘缓存，可在线和离线工作。

✨ 支持自定义模板提供程序，并可程序化使用。

✨ 支持提取到子目录。

✨ 支持授权以下载私有模板

✨ 克隆后可选择使用 unjs/nypm 安装依赖。

✨ 通过 unjs/node-fetch-native 支持 HTTP 代理和原生 fetch。

用法 (CLI)

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

参数

• template: 模板名称或描述提供商、存储库、子目录和分支/引用的 URI。（参见示例）
• dir: 提取模板的相对或绝对路径。

选项

• --force: 即使目录已存在，也克隆到现有目录。
• --offline: 不尝试下载，使用缓存版本。
• --prefer-offline: 如果存在则使用缓存，否则尝试下载。
• --force-clean: ⚠️ 在克隆前递归删除任何现有目录或文件。
• --shell: ⚠️ 在克隆的目录中打开一个新的 shell 作为当前工作目录。（实验性功能）。
• --registry: 自定义注册表的 URL。（可通过 GIGET_REGISTRY 环境变量覆盖）。
• --no-registry: 禁用注册表查找和功能。
• --verbose: 显示详细的调试信息。
• --cwd: 设置当前工作目录，以便解析相对路径。
• --auth: 用于下载模板的自定义授权令牌。（可通过 GIGET_AUTH 环境变量覆盖）。
• --install: 克隆后使用 unjs/nypm 安装依赖。

示例

# Clone nuxt starter from giget template registry
npx giget@latest nuxt

# Clone the main branch of github.com/unjs/template to unjs-template directory
npx giget@latest gh:unjs/template

# Clone to myProject directory
npx giget@latest gh:unjs/template myProject

# Clone dev branch
npx giget@latest gh:unjs/template#dev

# Clone /test directory from main branch
npx giget@latest gh:unjs/template/test

# Clone from gitlab
npx giget@latest gitlab:unjs/template

# Clone from bitbucket
npx giget@latest bitbucket:unjs/template

# Clone from sourcehut
npx giget@latest sourcehut:pi0/unjs-template

# Clone from https URL (tarball)
npx giget@latest https://api.github.com/repos/unjs/template/tarball/main

# Clone from https URL (JSON)
npx giget@latest https://raw.githubusercontent.com/unjs/giget/main/templates/unjs.json

模板注册表

Giget 有一个内置的 HTTP 注册表系统来解析模板。通过这种方式，您可以支持模板名称快捷方式和元数据。默认注册表从 unjs/giget/templates 提供服务。

如果您想将模板添加到内置注册表，只需提交 PR 将其添加到 https://raw.githubusercontent.com/unjs/giget/main/templates 目录。Slug 按照先到先得的原则添加，但未来可能会改变。

自定义注册表

自定义注册表应提供一个带有动态路径 /:template.json 的端点，该端点返回一个 JSON 响应，其键与自定义提供商相同。

• name: （必填）模板名称。
• tar （必填）tar 下载链接。
• defaultDir: （可选）默认克隆目录。
• url: （可选）模板的网页。
• subdir: （可选）tar 文件内的目录。
• headers: （可选）下载模板时发送的自定义头部。

由于其简洁性，您甚至可以使用 GitHub 仓库作为模板注册表，也可以通过引入自己的 API 构建更强大的功能。

用法 (程序化)

安装包

# npm
npm install giget

# yarn
yarn install giget

# pnpm
pnpm install giget

导入

// ESM
import { downloadTemplate } from "giget";

// CommonJS
const { downloadTemplate } = require("giget");

downloadTemplate(source, options?)

示例

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

选项

• source: (字符串) 输入源，格式为 [provider]:repo[/subpath][#ref]。
• options: (对象) 选项通常从输入字符串推断。您可以自定义它们。
  • dir: (字符串) 克隆到的目标目录。如果未提供，将使用相对于当前目录的 user-name。
  • provider: (字符串) 可以是 github、gitlab、bitbucket 或 sourcehut。默认值为 github。
  • force: (布尔值) 即使目录已存在，也提取到现有目录。
  • forceClean: (布尔值) ⚠️ 在克隆前清理任何现有目录或文件。
  • offline: (布尔值) 不尝试下载，使用缓存版本。
  • preferOffline: (布尔值) 如果存在则使用缓存，否则尝试下载。
  • providers: (对象) 从提供商名称到自定义提供商的映射。也可用于覆盖内置提供商。
  • registry: (字符串或布尔值) 设置为 false 以禁用注册表。对于自定义注册表，设置为 URL 字符串（不带斜杠）。（可通过 GIGET_REGISTRY 环境变量覆盖）。
  • cwd: (字符串) 当前工作目录，用于解析相对于它的目录。
  • auth: (字符串) 用于下载模板的自定义授权令牌。（可通过 GIGET_AUTH 环境变量覆盖）。

返回值

返回值是一个 Promise，它解析为已解析的模板。

• dir: (字符串) 提取目录的路径。
• source: (字符串) 不带提供商的输入源的标准化版本。
• 其他提供商模板键
  • url: (字符串) 可以在浏览器中打开的仓库 URL。对日志记录很有用。

自定义提供商

使用程序化方法，您可以创建自己的自定义模板提供商。

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 downloadRepo("rainbow:one", {
  providers: { rainbow },
});

自定义注册表提供商

您可以使用 registryProvider 工具定义额外的自定义注册表提供商，并注册到 providers。

import { registryProvider } from "giget";

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

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

为私有仓库提供令牌

对于私有仓库和源，您可能需要一个令牌。要提供令牌，在使用 CLI 时，您可以使用 --auth；在使用程序化 API 时，可以使用 auth 选项；在两种模式下，也可以使用 GIGET_AUTH 环境变量来设置它。默认情况下，该值将设置为 Authorization: Bearer ... 头部。

注意：对于使用细粒度访问令牌访问 GitHub 私有仓库，您需要授予内容（Contents）和元数据（Metadata）仓库权限。

相关项目

Giget 的开发离不开早期项目的启发。相比之下，giget 不依赖任何本地命令，这提高了稳定性和性能，并且开箱即用地支持自定义模板提供商、身份验证以及更多功能。

• https://github.com/samsonjs/gitter
• https://github.com/tiged/tiged
• https://github.com/Rich-Harris/degit

💻 开发

• 克隆此仓库
• 使用 Corepack 启用 corepack enable (Node.js < 16.10 请使用 npm i -g corepack)
• 使用 pnpm install 安装依赖项
• 使用 pnpm dev 运行交互式测试

许可

用心制作 💛

根据 MIT 许可证 发布。