degit — straightforward project scaffolding


degit makes copies of git repositories. When you run degit some-user/some-repo, it will find the latest commit on https://github.com/some-user/some-repo and download the associated tar file to ~/.degit/some-user/some-repo/commithash.tar.gz if it doesn't already exist locally. (This is much quicker than using git clone, because you're not downloading the entire git history.)

_Requires Node 8 or above, because async and await are the cat's pyjamas_

Installation

``bash
npm install -g degit
`

Usage

$3

The simplest use of degit is to download the master branch of a repo from GitHub to the current working directory:

`bash
degit user/repo

these commands are equivalent


degit github:user/repo
degit git@github.com:user/repo
degit https://github.com/user/repo
`

Or you can download from GitLab and BitBucket:

`bash


download from GitLab

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

download from BitBucket

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

download from Sourcehut

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

$3

The default branch is master.

`bash
degit user/repo#dev # branch
degit user/repo#v1.2.3 # release tag
degit user/repo#1234abcd # commit hash
``

$3

If the second argument is omitted, the repo will be cloned to the current directory.

`bash
degit user/repo my-new-project
`

$3

To clone a specific subdirectory instead of the entire repo, just add it to the argument:

`bash
degit user/repo/subdirectory
`

$3

If you have an https_proxy environment variable, Degit will use it.

$3

Private repos can be cloned by specifying --mode=git (the default is tar). In this mode, Degit will use git under the hood. It's much slower than fetching a tarball, which is why it's not the default.

Note: this clones over SSH, not HTTPS.

$3

`bash
degit --help
`

Not supported

- Private repositories

Pull requests are very welcome!

Wait, isn't this just git clone --depth 1?

A few salient differences:

- If you git clone, you get a .git folder that pertains to the project template, rather than your project. You can easily forget to re-init the repository, and end up confusing yourself
- Caching and offline support (if you already have a .tar.gz file for a specific commit, you don't need to fetch it again).
- Less to type (degit user/repo instead of git clone --depth 1 git@github.com:user/repo)
- Composability via actions
- Future capabilities — interactive mode, friendly onboarding and postinstall scripts

JavaScript API

You can also use degit inside a Node script:

`js
const degit = require('degit');

const emitter = degit('user/repo', {
cache: true,
force: true,
verbose: true,
});

emitter.on('info', info => {
console.log(info.message);
});

emitter.clone('path/to/dest').then(() => {
console.log('done');
});
`

Actions

You can manipulate repositories after they have been cloned with _actions_, specified in a degit.json file that lives at the top level of the working directory. Currently, there are two actions — clone and remove. Additional actions may be added in future.

$3

`json
// degit.json
[
{
"action": "clone",
"src": "user/another-repo"
}
]
`

This will clone user/another-repo, preserving the contents of the existing working directory. This allows you to, say, add a new README.md or starter file to a repo that you do not control. The cloned repo can contain its own degit.json actions.

$3

`json
// degit.json
[
{
"action": "remove",
"files": ["LICENSE"]
}
]
``

Remove a file at the specified path.

See also

- zel by Vu Tran
- gittar by Luke Edwards

License

MIT.