CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-degit

Straightforward project scaffolding tool that clones git repositories without history

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

cli.mddocs/

Command Line Interface

Full-featured CLI for interactive and scripted repository cloning with support for various options, interactive mode, and comprehensive help system.

Capabilities

Basic Command Usage

degit <src>[#ref] [<dest>] [options]

# Arguments:
# src    - Repository source (required for non-interactive mode)
# dest   - Destination directory (defaults to current directory)
# ref    - Branch, tag, or commit hash (optional, defaults to HEAD)

# Options:
# --help,    -h  Show help message
# --cache,   -c  Only use local cache
# --force,   -f  Allow non-empty destination directory
# --verbose, -v  Extra logging
# --mode=,   -m= Force the mode by which degit clones the repo (tar or git)

Basic Usage Examples:

# Clone to current directory
degit user/repo

# Clone to specific directory
degit user/repo my-project

# Clone specific branch
degit user/repo#develop my-project

# Clone specific tag
degit user/repo#v1.2.3 my-project

# Clone specific commit
degit user/repo#abcd1234 my-project

# Clone with options
degit user/repo my-project --force --verbose

Repository Source Formats

The CLI supports all the same repository source formats as the API:

# GitHub (default platform)
degit user/repo
degit github:user/repo
degit https://github.com/user/repo
degit git@github.com:user/repo

# GitLab
degit gitlab:user/repo
degit https://gitlab.com/user/repo
degit git@gitlab.com:user/repo

# BitBucket
degit bitbucket:user/repo
degit https://bitbucket.org/user/repo
degit git@bitbucket.org:user/repo

# Sourcehut
degit git.sr.ht/user/repo
degit git@git.sr.ht:user/repo
degit https://git.sr.ht/user/repo

# Subdirectory cloning
degit user/repo/path/to/subdir
degit user/repo/path/to/subdir#branch

Command Line Options

Help Option

degit --help
degit -h

Displays comprehensive help information including usage patterns, supported repository formats, and all available options.

Cache Option

degit user/repo --cache
degit user/repo -c

Forces degit to use only local cache without attempting to fetch new versions. Useful for offline development or when working with known stable versions.

Force Option

degit user/repo my-project --force
degit user/repo my-project -f

Allows cloning to non-empty destination directories. Without this option, degit will abort if the destination directory contains any files.

Verbose Option

degit user/repo my-project --verbose
degit user/repo my-project -v

Enables detailed logging showing download progress, extraction details, cache usage, and other operational information.

Mode Option

degit user/repo my-project --mode=tar
degit user/repo my-project --mode=git
degit user/repo my-project -m=tar
degit user/repo my-project -m=git

Forces specific cloning mode:

  • tar: Download repository as tar archive (default, faster)
  • git: Use git clone via SSH (required for private repositories)

Interactive Mode

When no source repository is specified, degit enters interactive mode with a fuzzy-searchable list of previously cloned repositories.

degit

Interactive Mode Features:

  • Repository Selection: Autocomplete search through previously cloned repositories
  • Fuzzy Search: Type partial names to filter repository list
  • Access History: Repositories sorted by most recently accessed
  • Destination Input: Specify target directory interactively
  • Cache Option: Choose whether to use cached version
  • Force Option: Handle non-empty directories interactively

Interactive Mode Example Session:

$ degit
? Repo to clone? › (Type to search)
❯ github:user/popular-repo#main
  gitlab:team/project#develop
  bitbucket:org/legacy-app#v2.1.0
  github:user/starter-template#latest

? Destination directory? › ./my-new-project
? Use cached version? › No
? Overwrite existing files? › Yes

> cloned github:user/popular-repo#main to ./my-new-project

Error Handling and Exit Codes

The CLI provides clear error messages and appropriate exit codes for scripting:

# Exit codes:
# 0 - Success
# 1 - Error (repository not found, network issues, validation errors, etc.)

Common Error Scenarios:

# Repository not found
$ degit nonexistent/repo
! could not parse nonexistent/repo

# Destination not empty (without --force)
$ degit user/repo existing-dir
! destination directory is not empty, aborting. Use --force to override

# Network issues
$ degit user/repo --cache
! could not find commit hash for main

# Invalid reference
$ degit user/repo#invalid-branch
! could not find commit hash for invalid-branch

Advanced Usage Patterns

Scripted Deployment

#!/bin/bash
# Deploy script using degit

set -e

# Clone specific version
degit myorg/app-template#v2.1.0 ./app --force --verbose

# Navigate and setup
cd app
npm install
npm run build

Template Generation

# Create new project from template
degit template-org/react-starter my-react-app
cd my-react-app

# Template may include degit.json for post-clone actions
# degit will automatically run these actions after cloning

Monorepo Subdirectory Cloning

# Clone only specific package from monorepo
degit facebook/react/packages/react my-react-clone

# Clone with specific version
degit facebook/react/packages/react-dom#v18.2.0 react-dom-source

Private Repository Access

# Use git mode for private repositories (requires SSH key setup)
degit git@github.com:private-org/private-repo private-project --mode=git

# Or use SSH URL format (automatically uses git mode)
degit git@gitlab.com:team/secret-project.git secret --verbose

Environment Variables

The CLI respects certain environment variables:

# HTTPS proxy support
export https_proxy=http://proxy.company.com:8080
degit user/repo my-project

# Home directory override
export HOME=/custom/home
degit user/repo  # Cache stored in /custom/home/.degit

Cache Management

Degit maintains a local cache in ~/.degit/ with the following structure:

~/.degit/
├── github/
│   └── user/
│       └── repo/
│           ├── abcd1234.tar.gz    # Cached tar files
│           ├── map.json           # Commit hash mappings
│           └── access.json        # Access timestamps
├── gitlab/
└── bitbucket/

Cache-Related Commands:

# Use only cache (no network requests)
degit user/repo --cache

# Force refresh (ignore cache)
degit user/repo  # Default behavior

# View cache location
ls ~/.degit

Help System

The built-in help system provides comprehensive usage information:

$ degit --help

degit

Usage:

`degit <src>[#ref] [<dest>] [options]`

Fetches the `src` repo, and extracts it to `dest` (or the current directory).

The `src` argument can be any of the following:

## GitHub repos

user/repo
github:user/repo
https://github.com/user/repo

## GitLab repos

gitlab:user/repo
https://gitlab.com/user/repo

## BitBucket repos

bitbucket:user/repo
https://bitbucket.com/user/repo

## Sourcehut repos

git.sr.ht/user/repo
git@git.sr.ht:user/repo
https://git.sr.ht/user/repo

You can append a #ref to any of the above:

## Branches (defaults to master)

user/repo#dev

## Tags

user/repo#v1.2.3

## Commit hashes

user/repo#abcd1234

The `dest` directory (or the current directory, if unspecified) must be empty
unless the `--force` option is used.

Options:

  `--help`,    `-h`  Show this message
  `--cache`,   `-c`  Only use local cache
  `--force`,   `-f`  Allow non-empty destination directory
  `--verbose`, `-v`  Extra logging
  `--mode=`,   `-m=` Force the mode by which degit clones the repo
                     Valid options are `tar` or `git` (uses SSH)

See https://github.com/Rich-Harris/degit for more information

Install with Tessl CLI

npx tessl i tessl/npm-degit

docs

actions.md

cli.md

cloning.md

index.md

tile.json