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
npm install -g degit
The simplest use of degit is to download the master branch of a repo from GitHub to the current working directory:
degit user/repo
# these commands are equivalent
degit github:user/repo
degit [email protected]:user/repo
degit https://github.com/user/repo
Or you can download from GitLab and BitBucket:
# download from GitLab
degit gitlab:user/repo
degit [email protected]:user/repo
degit https://gitlab.com/user/repo
# download from BitBucket
degit bitbucket:user/repo
degit [email protected]:user/repo
degit https://bitbucket.org/user/repo
# download from Sourcehut
degit git.sr.ht/user/repo
degit [email protected]:user/repo
degit https://git.sr.ht/user/repo
The default branch is master
.
degit user/repo#dev # branch
degit user/repo#v1.2.3 # release tag
degit user/repo#1234abcd # commit hash
If the second argument is omitted, the repo will be cloned to the current directory.
degit user/repo my-new-project
To clone a specific subdirectory instead of the entire repo, just add it to the argument:
degit user/repo/subdirectory
If you have an https_proxy
environment variable, Degit will use it.
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.
degit --help
- Private repositories
Pull requests are very welcome!
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 ofgit clone --depth 1 [email protected]:user/repo
) - Composability via actions
- Future capabilities — interactive mode, friendly onboarding and postinstall scripts
You can also use degit inside a Node script:
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');
});
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 three actions — clone
, remove
, and search_replace
. Additional actions may be added in future.
// 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.
// degit.json
[
{
"action": "remove",
"files": ["LICENSE"]
}
]
Remove a file at the specified path.
// degit.json
[
{
"action": "search_replace",
"files": [
"one.txt",
"two.json",
"three.mjs"
],
"pattern": "\\{\\{name\\}\\}",
"replacement": "PROJECT_NAME"
}
]
This will perform a search-and-replace in the given plaintext files. For example, this can be used to populate a project with an initial name, or various "author" references with email addresses, etc. The replacement regular expression is defined by the pattern
field; matches in those files will be replaced by the value of the environmental variable identified by the replacement
value in the user runtime. For example, the configuration listed above will replace all occurances of {{name}}
in the given files with the value of the environmental variable $PROJECT_NAME
.
- zel by Vu Tran
- gittar by Luke Edwards
MIT.