### Custom project setup with shell

Source: https://github.com/unjs/giget/blob/main/_autodocs/03-startShell.md

Sets up a new project from a template, installs dependencies, and then opens an interactive shell in the project directory, allowing immediate development. This combines template downloading, installation, and shell access.

```typescript
import { downloadTemplate, startShell } from "giget";

async function setupProject(template, projectName) {
  const result = await downloadTemplate(template, {
    dir: projectName,
    install: true
  });
  
  console.log("✓ Project setup complete");
  console.log(`✓ Dependencies installed");
  
  // User can now develop directly
  startShell(result.dir);
}

setupProject("nuxt", "my-app");
```

--------------------------------

### Install Git for Command Line Usage

Source: https://github.com/unjs/giget/blob/main/_autodocs/10-errors.md

Instructions for installing Git on macOS, Ubuntu/Debian, and Windows. Verify the installation by checking the Git version.

```bash
# Install git (macOS)
brew install git

# Install git (Ubuntu/Debian)
sudo apt-get install git

# Install git (Windows)
# Download from https://git-scm.com/download/win

# Verify installation
git --version
```

--------------------------------

### Monorepo Setup with Giget

Source: https://github.com/unjs/giget/blob/main/_autodocs/11-advanced-usage.md

Use `downloadTemplate` to initialize multiple packages within a monorepo structure. This example demonstrates downloading different templates for distinct packages concurrently.

```typescript
import { downloadTemplate } from "giget";

interface Package {
  name: string;
  template: string;
}

const monorepo: Package[] = [
  { name: "web", template: "gh:org/web-template" },
  { name: "api", template: "gh:org/api-template" },
  { name: "cli", template: "gh:org/cli-template" }
];

async function initializeMonorepo(rootDir: string) {
  const { mkdir } = await import("fs/promises");
  const { resolve } = await import("path");

  // Create root structure
  await mkdir(resolve(rootDir, "packages"), { recursive: true });

  // Download each package
  const results = await Promise.allSettled(
    monorepo.map((pkg) =>
      downloadTemplate(pkg.template, {
        dir: resolve(rootDir, "packages", pkg.name)
      })
    )
  );

  // Report
  results.forEach((result, idx) => {
    const pkg = monorepo[idx];
    if (result.status === "fulfilled") {
      console.log(`✓ ${pkg.name} initialized`);
    } else {
      console.error(`✗ ${pkg.name} failed:`, result.reason);
    }
  });
}

initializeMonorepo("./my-monorepo");

```

--------------------------------

### Complete TemplateInfo Example

Source: https://github.com/unjs/giget/blob/main/_autodocs/05-types.md

An example demonstrating a comprehensive TemplateInfo object, including version, subdirectory, URL, default directory, and custom headers.

```typescript
// Complete template info
const info: TemplateInfo = {
  name: "nuxt-starter",
  version: "3.5.0",
  tar: "https://api.github.com/repos/nuxt/starter/tarball/main",
  subdir: "/template",
  url: "https://github.com/nuxt/starter",
  defaultDir: "nuxt-app",
  headers: {
    "Authorization": "Bearer token123",
    "User-Agent": "giget/3.3.0"
  }
};
```

--------------------------------

### Install Dependencies

Source: https://github.com/unjs/giget/blob/main/README.md

Installs project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Custom TemplateProvider Implementation Example

Source: https://github.com/unjs/giget/blob/main/_autodocs/05-types.md

Demonstrates how to implement a custom TemplateProvider. This example handles inputs prefixed with 'custom:' and constructs a TemplateInfo object with a tarball URL and authorization headers.

```typescript
import type { TemplateProvider } from "giget";

const customProvider: TemplateProvider = async (input, { auth }) => {
  // Check if this provider should handle the input
  if (!input.startsWith("custom:")) {
    return null;
  }

  const templateId = input.slice(7);  // Remove "custom:" prefix

  return {
    name: templateId,
    version: "1.0.0",
    tar: `https://example.com/templates/${templateId}.tar.gz`,
    url: `https://example.com/templates/${templateId}`,
    headers: {
      authorization: auth ? `Bearer ${auth}` : undefined
    }
  };
};

// Register and use
const result = await downloadTemplate("custom:my-template", {
  providers: { custom: customProvider }
});
```

--------------------------------

### Custom Provider Implementation (Metadata)

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Example of creating a custom template provider that returns metadata. It checks if the input starts with a specific prefix and returns template details including a tarball URL.

```typescript
import type { TemplateProvider } from "giget";

const myProvider: TemplateProvider = async (input, { auth }) => {
  // Return null if input doesn't match this provider's format
  if (!input.startsWith("my-org:")) {
    return null;
  }

  return {
    name: "my-template",
    version: input,
    tar: `https://example.com/templates/${input}.tar.gz`,
    url: `https://example.com/templates/${input}`,
    headers: {
      authorization: auth ? `Bearer ${auth}` : undefined
    }
  };
};

// Use in downloadTemplate
const result = await downloadTemplate("my-org:template-v1", {
  providers: { "my-org": myProvider }
});
```

--------------------------------

### Install Dependencies

Source: https://github.com/unjs/giget/blob/main/_autodocs/08-cli.md

Automatically detects and installs project dependencies after cloning.

```bash
# Auto-detect package manager and install
giget nuxt --install

# Dependencies installed in extracted directory
```

--------------------------------

### Download Template using Git (Bitbucket Shorthand)

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Example of downloading a template from Bitbucket using its specific shorthand notation.

```typescript
// Bitbucket
downloadTemplate("bitbucket+git:user/repo")
```

--------------------------------

### Install Giget Package

Source: https://github.com/unjs/giget/blob/main/README.md

Install the giget package using npm, yarn, or pnpm.

```sh
# npm
npm install giget
```

```sh
# yarn
yarn install giget
```

```sh
# pnpm
pnpm install giget
```

--------------------------------

### Install Dependencies

Source: https://github.com/unjs/giget/blob/main/_autodocs/00-index.md

Automatically install project dependencies after downloading the template.

```typescript
const result = await downloadTemplate("nuxt", {
  install: true
});
```

--------------------------------

### Direct Tarball Download Example

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Demonstrates downloading a template directly from a tarball URL, such as from GitHub.

```typescript
// Direct tarball
downloadTemplate("https://api.github.com/repos/unjs/template/tarball/main")
```

--------------------------------

### Custom Server Tarball Download Example

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Illustrates downloading a template tarball from a custom server URL.

```typescript
// Custom server
downloadTemplate("https://example.com/my-template.tar.gz")
```

--------------------------------

### Clone Nuxt Starter from Giget Registry

Source: https://github.com/unjs/giget/blob/main/README.md

Example of cloning a starter template using the Giget CLI from its default template registry.

```bash
npx giget@latest nuxt
```

--------------------------------

### Minimal TemplateInfo Example

Source: https://github.com/unjs/giget/blob/main/_autodocs/05-types.md

A basic example of TemplateInfo with only the required 'name' and 'tar' (as a URL) fields.

```typescript
// Minimal template info
const info: TemplateInfo = {
  name: "my-template",
  tar: "https://example.com/template.tar.gz"
};
```

--------------------------------

### Download Template from GitLab.com

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Example of downloading a template from a simple GitLab project.

```typescript
// Simple project
downloadTemplate("gitlab:unjs/template")
// -> tarball: https://gitlab.com/unjs/template/-/archive/main.tar.gz
```

--------------------------------

### Download Template Example

Source: https://github.com/unjs/giget/blob/main/README.md

Use the downloadTemplate function to download a template from a GitHub repository. The destination directory will be inferred if not specified.

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

--------------------------------

### JSON Registry File Download Example

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Shows how to download a template from a JSON registry file, which Giget can parse for template information.

```typescript
// JSON registry file
downloadTemplate("https://raw.githubusercontent.com/unjs/giget/main/templates/nuxt.json")
```

--------------------------------

### CI/CD Environment Setup

Source: https://github.com/unjs/giget/blob/main/_autodocs/09-configuration.md

Configure Giget in CI/CD environments like GitHub Actions using environment variables for authentication and registry settings.

```yaml
# GitHub Actions
env:
  DEBUG: "1"
  GIGET_AUTH: ${{ secrets.GITHUB_TOKEN }}
  GIGET_REGISTRY: "https://templates.internal.company.com"

# Or in workflow step
- name: Clone template
  env:
    DEBUG: "1"
    GIGET_AUTH: ${{ secrets.GH_TOKEN }}
  run: giget gh:my-org/template --verbose
```

--------------------------------

### Git Provider Input Parsing Examples

Source: https://github.com/unjs/giget/blob/main/_autodocs/07-git-provider.md

Demonstrates how various git URI formats are parsed and converted into a standardized URL, with optional reference and subdirectory extraction.

```text
https://github.com/unjs/template
  -> https://github.com/unjs/template

gh:unjs/template
  -> https://github.com/unjs/template

gh:unjs/template#dev
  -> https://github.com/unjs/template, ref: dev

gh:unjs/template#main:src
  -> https://github.com/unjs/template, ref: main, subdir: src

git@github.com:unjs/template
  -> git@github.com:unjs/template (unchanged)

./local/repo
  -> /full/path/to/cwd/local/repo (absolute path)

gitlab:group/subgroup/repo
  -> https://gitlab.com/group/subgroup/repo
```

--------------------------------

### Download Template from SourceHut

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Example of downloading a basic repository from SourceHut using the `downloadTemplate` function.

```typescript
// Basic repo
downloadTemplate("sourcehut:user/repo")
// -> https://git.sr.ht/~user/repo/archive/main.tar.gz
```

--------------------------------

### Example Usage of downloadTemplate

Source: https://github.com/unjs/giget/blob/main/_autodocs/05-types.md

Demonstrates how to use the `downloadTemplate` function and illustrates the structure of the returned `DownloadTemplateResult` object.

```typescript
const result = await downloadTemplate("gh:unjs/template#dev");
// {
//   dir: "/home/user/unjs-template",
//   source: "unjs/template",
//   name: "unjs-template",
//   version: "dev",
//   url: "https://github.com/unjs/template/tree/dev",
//   tar: "https://api.github.com/repos/unjs/template/tarball/dev",
//   headers: { ... }
// }
```

--------------------------------

### Docker Container Setup

Source: https://github.com/unjs/giget/blob/main/_autodocs/09-configuration.md

Set up Giget within a Docker container, configuring cache directories and debug logging via environment variables.

```dockerfile
FROM node:22-slim

# Set cache directory to volume mount
ENV XDG_CACHE_HOME=/app/cache

# Enable debug by default in dev
ENV DEBUG=${DEBUG:-0}

WORKDIR /app

RUN npm install -g giget

# Usage: docker run -e GIGET_REGISTRY=... myimage
```

--------------------------------

### Successful Extraction Example

Source: https://github.com/unjs/giget/blob/main/_autodocs/08-cli.md

An example of the success message format when cloning a template named 'unjs-template' to 'my-project'.

```bash
✨ Successfully cloned `unjs-template` to `my-project`
```

--------------------------------

### Download Template from Bitbucket Cloud

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Example of downloading a template from a basic Bitbucket Cloud repository.

```typescript
// Basic repo
downloadTemplate("bitbucket:user/repo")
// -> https://bitbucket.org/user/repo/get/main.tar.gz
```

--------------------------------

### Download Template using Git (GitLab Shorthand)

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Example of downloading a template from GitLab using its specific shorthand notation.

```typescript
// GitLab
downloadTemplate("gitlab+git:group/project")
```

--------------------------------

### Download Template using Git (Shorthand with Branch)

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Example of downloading a template from a Git repository using a shorthand notation and specifying a branch.

```typescript
// Shorthand with branch
downloadTemplate("git:unjs/template#dev")
// -> Converts to https://github.com/unjs/template#dev
```

--------------------------------

### Download Template from Self-Hosted GitLab

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Example demonstrating how to download a template from a self-hosted GitLab instance by setting the GIGET_GITLAB_URL environment variable.

```bash
GIGET_GITLAB_URL=https://gitlab.internal giget gitlab:org/repo
```

--------------------------------

### Clone using Local Git Provider

Source: https://github.com/unjs/giget/blob/main/README.md

Clones a repository using the local Git installation via HTTPS, specifying the provider as 'git'. This is useful for repositories not directly supported by other providers or for custom Git setups.

```bash
npx giget@latest git:unjs/template
```

--------------------------------

### Use Registry via CLI

Source: https://github.com/unjs/giget/blob/main/_autodocs/02-registryProvider.md

Provides examples of using Giget from the command line to interact with registries. It shows how to use the default registry, specify a custom registry, and disable the registry.

```bash
# Use default built-in registry
giget nuxt

# Use custom registry URL
giget my-template --registry=https://templates.example.com

# Disable registry entirely
giget gh:unjs/template --no-registry
```

--------------------------------

### Install Dependencies After Cloning

Source: https://github.com/unjs/giget/blob/main/_autodocs/01-downloadTemplate.md

Automatically installs project dependencies after cloning the template. Giget can detect the package manager or you can specify it explicitly. The `cwd` option can be used to set the working directory for the installation.

```typescript
const result = await downloadTemplate("nuxt", {
  install: true  // Detects package manager automatically
});

// Or with custom options
const result = await downloadTemplate("nuxt", {
  install: {
    packageManager: "pnpm",  // Force specific package manager
    cwd: result.dir
  }
});
```

--------------------------------

### Download Template using Git (HTTPS)

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Example of downloading a template from a Git repository using an HTTPS URL.

```typescript
// HTTPS
downloadTemplate("git:https://github.com/unjs/template")
```

--------------------------------

### Download Template using Git (SSH)

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Example of downloading a template from a Git repository using an SSH URI.

```typescript
// SSH
downloadTemplate("git:git@github.com:unjs/template")
```

--------------------------------

### Programmatic shell launch with error handling

Source: https://github.com/unjs/giget/blob/main/_autodocs/03-startShell.md

Demonstrates how to download a template and then offer the user an option to open an interactive shell in the cloned directory, with basic error handling. Ensures the environment is a TTY before attempting to start the shell.

```typescript
import { downloadTemplate, startShell } from "giget";

try {
  const result = await downloadTemplate("gh:unjs/template");
  console.log(`Template cloned to: ${result.dir}`);
  
  // Give user option to open shell
  if (process.stdin.isTTY) {
    startShell(result.dir);
  }
} catch (error) {
  console.error("Failed to download template:", error);
}
```

--------------------------------

### Download Template using Git (Local Path)

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Examples of downloading a template from a local Git repository using relative or absolute paths.

```typescript
// Local repo
downloadTemplate("git:./path/to/repo")
downloadTemplate("git:/absolute/path/to/repo")
```

--------------------------------

### Download Template using Git (Sparse Checkout)

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Example of downloading only a specific subdirectory from a Git repository using sparse checkout.

```typescript
// Sparse checkout (subdirectory only)
downloadTemplate("git:https://github.com/unjs/template#main:src")
// -> Fetches only /src directory
```

--------------------------------

### Download Template from Bitbucket with Specific Tag

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Example of downloading a template from a Bitbucket Cloud repository using a specific version tag.

```typescript
// Specific tag
downloadTemplate("bitbucket:user/repo#v1.0")
```

--------------------------------

### TemplateInfo with Function-Based Tar Example

Source: https://github.com/unjs/giget/blob/main/_autodocs/05-types.md

Shows how to use a function for the 'tar' field to provide a streaming TarOutput, including handling authentication headers.

```typescript
// With function-based tar (streaming)
const info: TemplateInfo = {
  name: "streaming-template",
  tar: async ({ auth }) => {
    const response = await fetch("https://example.com/template.tar.gz", {
      headers: { authorization: `Bearer ${auth}` }
    });
    return response.body;  // ReadableStream<Uint8Array>
  }
};
```

--------------------------------

### Convert Markdown to PDF

Source: https://github.com/unjs/giget/blob/main/_autodocs/README.md

Use pandoc to convert all markdown files in the current directory to a single PDF file. Ensure pandoc is installed.

```bash
# Convert to PDF
pandoc *.md -o documentation.pdf
```

--------------------------------

### TemplateInfo with Custom Fields Example

Source: https://github.com/unjs/giget/blob/main/_autodocs/05-types.md

Illustrates how to include arbitrary custom fields within the TemplateInfo object, which are passed through by giget.

```typescript
// With custom fields
const info: TemplateInfo = {
  name: "premium-template",
  tar: "https://example.com/templates/premium.tar.gz",
  customField: "custom-value",
  metadata: { category: "web-app" }
};
```

--------------------------------

### Convert Markdown to HTML

Source: https://github.com/unjs/giget/blob/main/_autodocs/README.md

Use pandoc to convert all markdown files in the current directory to a single HTML file. Ensure pandoc is installed.

```bash
# Convert to HTML
pandoc *.md -o documentation.html
```

--------------------------------

### Download Template from GitLab with Subdirectory and Specific Branch

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Example of downloading a template from a GitLab project located in a subgroup, specifying a subdirectory and a development branch.

```typescript
// Project in subgroup with subdirectory
downloadTemplate("gitlab:group/subgroup/project::src#dev")
// -> extracts /src from dev branch
```

--------------------------------

### Git Clone Provider Usage Examples

Source: https://github.com/unjs/giget/blob/main/README.md

The `git:` provider clones repositories directly using the local `git` command. It supports various formats for specifying the repository, branch/tag, commit, and subdirectory.

```sh
git:unjs/template                    # HTTPS clone (github.com by default)
git:unjs/template#v2                 # Specific branch or tag
git:unjs/template#e24616c            # Specific commit (full clone fallback)
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)
```

--------------------------------

### Download Template from HTTPS

Source: https://github.com/unjs/giget/blob/main/_autodocs/07-git-provider.md

Clones a template directly from a GitHub HTTPS URL. No specific setup is required beyond importing the function.

```typescript
import { downloadTemplate } from "giget";

const result = await downloadTemplate(
  "git:https://github.com/unjs/template"
);
```

--------------------------------

### DownloadTemplateOptions Interface

Source: https://github.com/unjs/giget/blob/main/_autodocs/05-types.md

Defines the configuration options available when downloading a template. These options control aspects like provider selection, force re-downloading, offline usage, and installation behavior.

```typescript
export interface DownloadTemplateOptions {
  provider?: string;
  force?: boolean;
  forceClean?: boolean;
  offline?: boolean;
  preferOffline?: boolean;
  providers?: Record<string, TemplateProvider>;
  dir?: string;
  registry?: false | string;
  cwd?: string;
  auth?: string;
  install?: boolean | InstallOptions;
  silent?: boolean;
  ignore?: ((path: string) => boolean) | string[];
}
```

--------------------------------

### Import Core Giget API Functions

Source: https://github.com/unjs/giget/blob/main/_autodocs/00-index.md

Import the main functions for downloading templates, creating custom registries, and starting an interactive shell from the giget package.

```typescript
import { downloadTemplate, registryProvider, startShell } from "giget"
```

--------------------------------

### Project Creation with Post-Download Customization

Source: https://github.com/unjs/giget/blob/main/_autodocs/11-advanced-usage.md

This function downloads a project template and then applies customizations such as creating a .env file, removing specified files, and renaming directories. It requires a configuration object detailing the template, project name, and customization steps.

```typescript
import { downloadTemplate, startShell } from "giget";
import { writeFile, readFile } from "fs/promises";
import { resolve } from "path";

interface ProjectConfig {
  name: string;
  template: string;
  customize?: {
    env?: Record<string, string>;
    removeFiles?: string[];
    renameDirs?: Record<string, string>;
  };
}

async function createProjectWithCustomization(config: ProjectConfig) {
  const result = await downloadTemplate(config.template, {
    dir: config.name
  });

  if (!config.customize) {
    return result;
  }

  const { env, removeFiles, renameDirs } = config.customize;

  // Create .env file
  if (env) {
    const envPath = resolve(result.dir, ".env");
    const envContent = Object.entries(env)
      .map(([k, v]) => `${k}=${v}`)
      .join("\n");
    await writeFile(envPath, envContent);
  }

  // Remove specified files
  if (removeFiles) {
    const { rm } = await import("fs/promises");
    for (const file of removeFiles) {
      await rm(resolve(result.dir, file), { force: true });
    }
  }

  // Rename directories
  if (renameDirs) {
    const { rename } = await import("fs/promises");
    for (const [oldName, newName] of Object.entries(renameDirs)) {
      const oldPath = resolve(result.dir, oldName);
      const newPath = resolve(result.dir, newName);
      try {
        await rename(oldPath, newPath);
      } catch (error) {
        console.warn(`Failed to rename ${oldName} to ${newName}`);
      }
    }
  }

  return result;
}

// Usage
const result = await createProjectWithCustomization({
  name: "my-app",
  template: "gh:org/template",
  customize: {
    env: { DEBUG: "true", API_URL: "http://localhost:3000" },
    removeFiles: ["CHANGELOG.md", ".git"],
    renameDirs: { "src": "app" }
  }
});

```

--------------------------------

### Giget CLI Quick Reference Commands

Source: https://github.com/unjs/giget/blob/main/AGENTS.md

Common commands for building, testing, linting, and running the Giget CLI. Ensure Node.js and pnpm are set up.

```bash
eval "$(fnm env --use-on-cd 2>/dev/null)"  # Enable node/pnpm
pnpm build          # Build with obuild (rolldown)
pnpm dev            # Run tests in watch mode
pnpm vitest run test/utils.test.ts   # Run a specific test
pnpm test           # Full: lint + typecheck + tests + coverage
pnpm lint:fix       # Oxlint + oxfmt auto-fix
pnpm giget          # Run CLI from source (node ./src/cli.ts)
```

--------------------------------

### Download Template from GitHub

Source: https://github.com/unjs/giget/blob/main/_autodocs/04-providers.md

Demonstrates various ways to use the `downloadTemplate` function with the GitHub provider, including simple repository download, specifying a branch, and extracting a subdirectory.

```bash
// Simple repo
downloadTemplate("gh:unjs/template")
// -> tarball: https://api.github.com/repos/unjs/template/tarball/main
```

```bash
// Specific branch
downloadTemplate("gh:unjs/template#dev")
// -> tarball with dev branch
```

```bash
// Subdirectory
downloadTemplate("gh:unjs/template/src")
// -> extracts only /src subdirectory
```

```bash
// Enterprise GitHub
GIGET_GITHUB_URL=https://github.enterprise.com/api/v3 giget gh:org/repo
```

--------------------------------

### Get Platform-Appropriate Cache Directory

Source: https://github.com/unjs/giget/blob/main/_autodocs/06-utilities.md

Use `cacheDirectory` to get the absolute path to the platform-appropriate cache directory for Giget. It follows XDG specifications on Linux/macOS and uses the system temp directory on Windows. On Windows, it can also migrate old cache locations.

```typescript
import { cacheDirectory } from "giget";

const cache = cacheDirectory();
// Linux/macOS: /home/user/.cache/giget
// Windows: C:\Users\user\AppData\Local\Temp\giget

const templateCache = `${cacheDirectory()}/github/unjs-template/main.tar.gz`;
```

--------------------------------

### currentShell

Source: https://github.com/unjs/giget/blob/main/_autodocs/06-utilities.md

Get the current shell command path. This is useful for interactive use cases.

```APIDOC
## currentShell

### Description
Get the current shell command path. This is useful for interactive use cases.

### Signature
```typescript
export function currentShell(): string
```

### Return Type
`string` — Shell command path

### Platform Behavior

| Platform | Return |
|----------|--------|
| Unix/Linux/macOS with `$SHELL` set | Value of `$SHELL` env var |
| Unix/Linux/macOS without `$SHELL` | `/bin/bash` |
| Windows | `cmd.exe` |
```

--------------------------------

### Get Current Shell Command

Source: https://github.com/unjs/giget/blob/main/_autodocs/06-utilities.md

Retrieves the path to the current shell command. This is useful for interactive use cases.

```typescript
export function currentShell(): string
```

--------------------------------

### Combination of Options

Source: https://github.com/unjs/giget/blob/main/_autodocs/08-cli.md

Demonstrates combining multiple options for a comprehensive cloning operation.

```bash
giget gh:unjs/template my-project \
  --force \
  --install \
  --ignore "*.md,tests/**" \
  --verbose
```

--------------------------------

### Custom Registry with Authentication

Source: https://github.com/unjs/giget/blob/main/_autodocs/02-registryProvider.md

Demonstrates setting up a custom registry provider for private templates that require authentication. It shows how to pass authentication tokens.

```typescript
const privateRegistry = registryProvider(
  "https://private.templates.internal/api",
  { auth: process.env.REGISTRY_TOKEN }
);

const result = await downloadTemplate("internal-template", {
  providers: { private: privateRegistry },
  auth: process.env.REGISTRY_TOKEN  // Also passed to tar download
});
```

--------------------------------

### Shell Integration

Source: https://github.com/unjs/giget/blob/main/_autodocs/08-cli.md

Clones a repository and then opens a shell within the cloned directory.

```bash
# Clone and open shell in directory
giget nuxt --shell

# User exits shell to return to command line
```

--------------------------------

### GitLab Repository Cloning

Source: https://github.com/unjs/giget/blob/main/_autodocs/08-cli.md

Shows how to clone from GitLab, including projects in subgroups and specifying subdirectories.

```bash
# Simple project
giget gitlab:unjs/template
```

```bash
# Project in subgroup with subdirectory (using :: separator)
giget gitlab:group/subgroup/project::src/template#dev
```

--------------------------------

### cacheDirectory

Source: https://github.com/unjs/giget/blob/main/_autodocs/06-utilities.md

Gets the platform-appropriate cache directory for giget. This function returns the absolute path to the cache directory, which varies based on the operating system.

```APIDOC
## cacheDirectory

Get the platform-appropriate cache directory for giget.

### Signature

```typescript
export function cacheDirectory(): string
```

### Return Type

`string` — Absolute path to cache directory

### Platform Behavior

| Platform | Location |
|----------|----------|
| Linux/macOS | `~/.cache/giget` or `$XDG_CACHE_HOME/giget` |
| Windows | `%TEMP%/giget` |

### Examples

```typescript
import { cacheDirectory } from "giget";

const cache = cacheDirectory();
// Linux/macOS: /home/user/.cache/giget
// Windows: C:\Users\user\AppData\Local\Temp\giget

const templateCache = `${cacheDirectory()}/github/unjs-template/main.tar.gz`;
```
```

--------------------------------

### Parse HTTPS Git URI

Source: https://github.com/unjs/giget/blob/main/_autodocs/07-git-provider.md

Parses a standard HTTPS Git URI. Use this to get a structured representation of a remote repository URL.

```typescript
import { parseGitCloneURI } from "giget";

// HTTPS
parseGitCloneURI("https://github.com/unjs/template")
// -> { uri: "https://github.com/unjs/template", name: "unjs-template" }
```

--------------------------------

### Use Built-in Giget Registry

Source: https://github.com/unjs/giget/blob/main/_autodocs/02-registryProvider.md

Demonstrates downloading a template using the default built-in Giget registry. No special configuration is needed as it's the default behavior.

```typescript
import { registryProvider, downloadTemplate } from "giget";

// Built-in registry is used by default when no provider prefix in input
const result = await downloadTemplate("nuxt");
// Internally fetches from https://raw.githubusercontent.com/unjs/giget/main/templates/nuxt.json
```

--------------------------------

### Basic Registry Lookup

Source: https://github.com/unjs/giget/blob/main/_autodocs/08-cli.md

Clones a template from the Giget registry to the current directory.

```bash
npx giget@latest nuxt
# Clones from giget registry to ./nuxt directory
```

--------------------------------

### startShell Function

Source: https://github.com/unjs/giget/blob/main/_autodocs/03-startShell.md

Opens an interactive shell with the current working directory set to a specified path. This function is blocking and requires a TTY.

```APIDOC
## startShell

### Description
Opens an interactive shell with the current working directory set to a specified path. This function is blocking and requires a TTY.

### Signature
```typescript
export function startShell(cwd: string): void
```

### Parameters
#### Path Parameters
- **cwd** (`string`) - Required - Directory path to open shell in (resolved to absolute path)

### Return Type
`void` — Does not return a value (spawns a blocking shell process)

### Throws
No exceptions thrown. Errors are handled silently (e.g., if shell is not found).

### Usage Examples
#### Open shell in extracted template directory
```typescript
import { downloadTemplate, startShell } from "giget";

const result = await downloadTemplate("nuxt");
startShell(result.dir);
// Opens interactive shell in the extracted template directory
```

#### Programmatic shell launch with error handling
```typescript
import { downloadTemplate, startShell } from "giget";

try {
  const result = await downloadTemplate("gh:unjs/template");
  console.log(`Template cloned to: ${result.dir}`);
  
  // Give user option to open shell
  if (process.stdin.isTTY) {
    startShell(result.dir);
  }
} catch (error) {
  console.error("Failed to download template:", error);
}
```

#### Relative to working directory
```typescript
import { startShell } from "giget";

// Shell resolves relative path to absolute
startShell("./my-project");
// Opens shell in /current/working/directory/my-project
```
```

--------------------------------

### Open shell in extracted template directory

Source: https://github.com/unjs/giget/blob/main/_autodocs/03-startShell.md

Use after downloading a template to open an interactive shell in the template's root directory. Requires 'giget' to be installed.

```typescript
import { downloadTemplate, startShell } from "giget";

const result = await downloadTemplate("nuxt");
startShell(result.dir);
// Opens interactive shell in the extracted template directory
```

--------------------------------

### GitHub Repository Cloning

Source: https://github.com/unjs/giget/blob/main/_autodocs/08-cli.md

Demonstrates various ways to clone from GitHub repositories, including specific branches, subdirectories, and target directories.

```bash
# Clone latest version
giget gh:unjs/template
```

```bash
# Clone to specific directory
giget gh:unjs/template my-project
```

```bash
# Clone specific branch
giget gh:unjs/template#dev
```

```bash
# Clone subdirectory only
giget gh:unjs/template/src
```

```bash
# Clone subdir from specific branch
giget gh:unjs/template#main/templates
```

--------------------------------

### Use Registry Shortcut

Source: https://github.com/unjs/giget/blob/main/_autodocs/00-index.md

Download a template using a shortcut name registered in the Giget registry.

```typescript
const result = await downloadTemplate("nuxt");  // From registry
```

--------------------------------

### Wrap Built-in Template Provider

Source: https://github.com/unjs/giget/blob/main/_autodocs/11-advanced-usage.md

Extend existing providers by wrapping them with custom logic. This example wraps the built-in GitHub provider to add custom headers to requests.

```typescript
import type { TemplateProvider } from "giget";
import { providers, downloadTemplate } from "giget";

const cachedGithub: TemplateProvider = async (input, options) => {
  // Use built-in GitHub provider
  const baseResult = await providers.github(input, options);
  
  if (baseResult) {
    // Customize headers
    baseResult.headers = {
      ...baseResult.headers,
      "x-custom-header": "custom-value"
    };
  }
  
  return baseResult;
};

const result = await downloadTemplate("gh:unjs/template", {
  providers: { gh: cachedGithub, github: cachedGithub }
});
```

--------------------------------

### Giget CLI Basic Usage

Source: https://github.com/unjs/giget/blob/main/_autodocs/08-cli.md

The fundamental command structure for using the giget CLI to download a template to a specified directory.

```bash
giget <template> [<dir>] [options]
```

--------------------------------

### Create and Use Custom Registry Provider

Source: https://github.com/unjs/giget/blob/main/_autodocs/02-registryProvider.md

Shows how to define a custom registry provider and use it for downloading templates. This is useful for private or alternative template sources.

```typescript
import { registryProvider, downloadTemplate } from "giget";

const companyRegistry = registryProvider(
  "https://templates.company.com/api/registry"
);

const result = await downloadTemplate("my-template", {
  providers: { custom: companyRegistry }
});
// Would use: giget:my-template or pass custom provider explicitly
```

--------------------------------

### CLI usage with --shell flag

Source: https://github.com/unjs/giget/blob/main/_autodocs/03-startShell.md

Illustrates how to use the giget CLI to clone a template and automatically open an interactive shell in the cloned directory using the `--shell` flag.

```bash
giget nuxt --shell
# Clones template and opens shell in the directory
```

--------------------------------

### Disable Registry (Force Direct Provider)

Source: https://github.com/unjs/giget/blob/main/_autodocs/09-configuration.md

Bypass the template registry and use the direct provider (e.g., GitHub) by using the --no-registry flag or setting registry to false programmatically.

```bash
# CLI
giget gh:unjs/template --no-registry
```

```javascript
# Programmatically
const result = await downloadTemplate("gh:unjs/template", {
  registry: false
});
// Skips registry lookup, uses github provider directly
```

--------------------------------

### Git Authentication Environment Variables

Source: https://github.com/unjs/giget/blob/main/_autodocs/07-git-provider.md

Authentication tokens are passed via environment variables to prevent exposure in process listings. This setup configures Git to use an Authorization header and disables interactive prompts.

```typescript
const execEnv = {
  ...process.env,
  GIT_CONFIG_COUNT: "1",
  GIT_CONFIG_KEY_0: "http.extraHeader",
  GIT_CONFIG_VALUE_0: "Authorization: Bearer {token}",
  GIT_TERMINAL_PROMPT: "0"  // Disable interactive prompts
};
```

--------------------------------

### Handle Download Errors

Source: https://github.com/unjs/giget/blob/main/_autodocs/01-downloadTemplate.md

Demonstrates how to catch and handle potential errors during template download, such as unsupported providers, existing directories, or missing cached templates when offline.

```typescript
try {
  const result = await downloadTemplate("gh:invalid/repo");
} catch (error) {
  if (error instanceof Error) {
    if (error.message.includes("Unsupported provider")) {
      // Handle provider not found
    } else if (error.message.includes("already exists")) {
      // Handle directory exists (use force: true to override)
    } else if (error.message.includes("Tarball not found")) {
      // Handle offline without cache
    }
  }
}
```

--------------------------------

### Handle Specific Download Errors

Source: https://github.com/unjs/giget/blob/main/_autodocs/10-errors.md

Catches potential errors during template download and provides specific user feedback for common issues like existing directories, unsupported providers, network failures, or missing Git installations.

```typescript
import { downloadTemplate } from "giget";

try {
  const result = await downloadTemplate("gh:unjs/template", {
    dir: "my-project"
  });
} catch (error) {
  const message = error instanceof Error ? error.message : "Unknown error";
  
  if (message.includes("already exists")) {
    console.error("Directory exists. Use --force to overwrite.");
    // Offer user options
  } else if (message.includes("Unsupported provider")) {
    console.error("Invalid provider. Use: gh, gitlab, bitbucket, sourcehut, git, http, https");
  } else if (message.includes("Failed to download")) {
    console.error("Network error. Check connection and retry.");
  } else if (message.includes("git is not installed")) {
    console.error("Git is required for git: provider. Install git and try again.");
  } else {
    console.error("Error:", message);
  }
  
  process.exit(1);
}
```

--------------------------------

### Download from GitLab with Subgroups and Subdirectory

Source: https://github.com/unjs/giget/blob/main/_autodocs/01-downloadTemplate.md

Clones a template from GitLab, including support for subgroups and specifying a subdirectory within the repository. The `::` syntax is used to separate the repository path from the subdirectory when the repository path has more than two segments.

```typescript
const result = await downloadTemplate(
  "gitlab:group/subgroup/project::src/template#main",
  { dir: "output" }
);
// Uses :: to separate repo path from subdir when repo has >2 segments
```

--------------------------------

### Enhanced Fetch Requests with Giget

Source: https://github.com/unjs/giget/blob/main/_autodocs/06-utilities.md

The `sendFetch` function wraps the standard `fetch` API, providing error handling and optional status validation. It normalizes headers and wraps network errors with context. Use it for basic GET requests, authenticated requests, or requests that require status validation.

```typescript
import { sendFetch } from "giget";

// Basic GET
const response = await sendFetch("https://api.github.com/repos/unjs/template");
const data = await response.json();

// With auth header
const response = await sendFetch("https://private.example.com/template.tar.gz", {
  headers: { authorization: "Bearer token123" }
});

// With validation
const response = await sendFetch("https://registry.example.com/template.json", {
  validateStatus: true  // Throw if 4xx/5xx
});

// HEAD request
const response = await sendFetch("https://example.com/file.tar.gz", {
  method: "HEAD"
});
const contentType = response.headers.get("content-type");
```

--------------------------------

### Create a Simple Custom Template Provider

Source: https://github.com/unjs/giget/blob/main/_autodocs/11-advanced-usage.md

Implement a custom template provider by defining a function that returns template metadata. This provider only handles inputs prefixed with 'custom:'. Ensure the provider returns null if it cannot handle the input.

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

const customProvider: TemplateProvider = async (input, { auth }) => {
  // Only handle inputs starting with "custom:"
  if (!input.startsWith("custom:")) {
    return null;
  }

  const templateName = input.slice(7);

  return {
    name: templateName,
    version: "1.0.0",
    tar: `https://api.custom.com/templates/${templateName}.tar.gz`,
    url: `https://custom.com/templates/${templateName}`,
    headers: {
      authorization: auth ? `Bearer ${auth}` : undefined,
      "user-agent": "giget/3.3.0"
    }
  };
};

// Use it
const result = await downloadTemplate("custom:react-app", {
  providers: { custom: customProvider }
});
```

--------------------------------

### Download Template from Registry

Source: https://github.com/unjs/giget/blob/main/_autodocs/01-downloadTemplate.md

Clones a template from the default registry using a shortcut. The result contains the absolute path to the extracted template directory.

```typescript
import { downloadTemplate } from "giget";

const result = await downloadTemplate("nuxt");
console.log(result.dir);  // Absolute path to extracted template
```

--------------------------------

### Custom Registry Configuration

Source: https://github.com/unjs/giget/blob/main/_autodocs/08-cli.md

Uses a custom registry for cloning templates, configurable via command-line flag or environment variable.

```bash
# Use custom registry
giget my-template --registry https://templates.company.com
```

```bash
# Or via environment variable
export GIGET_REGISTRY=https://templates.company.com
giget my-template
```

--------------------------------

### Download Template to Custom Directory

Source: https://github.com/unjs/giget/blob/main/_autodocs/01-downloadTemplate.md

Clones a template from a specific provider (e.g., GitHub) and extracts it into a custom directory. Ensure the target directory does not already exist unless `forceClean` is used.

```typescript
const result = await downloadTemplate("gh:unjs/template", {
  dir: "my-project"
});
// Extracts to ./my-project
```

--------------------------------

### DownloadTemplateOptions

Source: https://github.com/unjs/giget/blob/main/_autodocs/05-types.md

Options that can be passed to the `downloadTemplate` function to customize its behavior. These include provider selection, force options, offline preferences, directory settings, authentication, and more.

```APIDOC
## DownloadTemplateOptions

### Description
Options passed to `downloadTemplate`.

### Interface
```typescript
export interface DownloadTemplateOptions {
  provider?: string;
  force?: boolean;
  forceClean?: boolean;
  offline?: boolean;
  preferOffline?: boolean;
  providers?: Record<string, TemplateProvider>;
  dir?: string;
  registry?: false | string;
  cwd?: string;
  auth?: string;
  install?: boolean | InstallOptions;
  silent?: boolean;
  ignore?: ((path: string) => boolean) | string[];
}
```
```

--------------------------------

### Private Repository with Token

Source: https://github.com/unjs/giget/blob/main/_autodocs/09-configuration.md

Authenticate with private repositories using tokens for GitHub, GitLab, and Bitbucket via the GIGET_AUTH environment variable or programmatically.

```bash
# GitHub token
export GIGET_AUTH=ghp_xxxxxxxxxxxxxxxxxxxx
giget gh:my-org/private-template

# GitLab token
export GIGET_AUTH=glpat-xxxxxxxxxxxxxxxxxxxx
giget gitlab:my-org/project

# Bitbucket token
export GIGET_AUTH=xxxxxxxxxxxxxxxxxxxxx
giget bitbucket:workspace/repo
```

```javascript
# Programmatically
const result = await downloadTemplate("gh:my-org/template", {
  auth: process.env.MY_TOKEN
});
```

--------------------------------

### Batch Download Templates

Source: https://github.com/unjs/giget/blob/main/_autodocs/11-advanced-usage.md

Process multiple templates concurrently using `Promise.all` and `downloadTemplate`. This function is designed to download and set up multiple project components, reporting success or failure for each.

```typescript
import { downloadTemplate } from "giget";

interface TemplateConfig {
  name: string;
  template: string;
  options?: Record<string, any>;
}

const templates: TemplateConfig[] = [
  { name: "frontend", template: "gh:org/frontend-template" },
  { name: "backend", template: "gh:org/backend-template" },
  { name: "shared", template: "gh:org/shared-libs" }
];

async function createProject(projectDir) {
  const results = await Promise.all(
    templates.map(async (config) => {
      try {
        const result = await downloadTemplate(config.template, {
          dir: `${projectDir}/${config.name}`,
          ...config.options
        });
        return { name: config.name, success: true, path: result.dir };
      } catch (error) {
        return {
          name: config.name,
          success: false,
          error: error instanceof Error ? error.message : "Unknown error"
        };
      }
    })
  );

  // Report results
  results.forEach((r) => {
    if (r.success) {
      console.log(`✓ ${r.name} → ${r.path}`);
    } else {
      console.error(`✗ ${r.name} → ${r.error}`);
    }
  });

  const failed = results.filter((r) => !r.success);
  if (failed.length > 0) {
    throw new Error(`Failed to create ${failed.length} components`);
  }

  return results;
}

await createProject("./my-monorepo");
```

--------------------------------

### Disable Registry and Use Direct Provider

Source: https://github.com/unjs/giget/blob/main/_autodocs/02-registryProvider.md

Illustrates how to disable the registry lookup entirely and force Giget to use a direct provider, such as GitHub. This is useful when you want to bypass the registry for specific downloads.

```typescript
const result = await downloadTemplate("gh:unjs/template", {
  registry: false  // Disables registry lookup entirely
});
// Forces direct GitHub provider, ignores registry
```

--------------------------------

### Authenticate with Bitbucket

Source: https://github.com/unjs/giget/blob/main/_autodocs/09-configuration.md

Use the GIGET_AUTH environment variable with an App Password or OAuth token for accessing private Bitbucket repositories.

```bash
export GIGET_AUTH=app-password-or-token
giget bitbucket:workspace/private-repo
```

--------------------------------

### Bitbucket Repository Cloning

Source: https://github.com/unjs/giget/blob/main/_autodocs/08-cli.md

Clones a repository from Bitbucket.

```bash
giget bitbucket:user/repo
```