1 | # degit — straightforward project scaffolding
|
2 |
|
3 | [![Travis CI build status](https://badgen.net/travis/Rich-Harris/degit/master)](https://travis-ci.org/Rich-Harris/degit)
|
4 | [![AppVeyor build status](https://badgen.net/appveyor/ci/Rich-Harris/degit/master)](https://ci.appveyor.com/project/Rich-Harris/degit/branch/master)
|
5 | [![Known Vulnerabilities](https://snyk.io/test/npm/degit/badge.svg)](https://snyk.io/test/npm/degit)
|
6 | [![install size](https://badgen.net/packagephobia/install/degit)](https://packagephobia.now.sh/result?p=degit)
|
7 | [![npm package version](https://badgen.net/npm/v/degit)](https://npm.im/degit)
|
8 | [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v1.4%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)
|
9 | [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
|
10 |
|
11 | **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.)
|
12 |
|
13 | _Requires Node 8 or above, because `async` and `await` are the cat's pyjamas_
|
14 |
|
15 | ## Installation
|
16 |
|
17 | ```bash
|
18 | npm install -g degit
|
19 | ```
|
20 |
|
21 | ## Usage
|
22 |
|
23 | ### Basics
|
24 |
|
25 | The simplest use of degit is to download the master branch of a repo from GitHub to the current working directory:
|
26 |
|
27 | ```bash
|
28 | degit user/repo
|
29 |
|
30 | # these commands are equivalent
|
31 | degit github:user/repo
|
32 | degit git@github.com:user/repo
|
33 | degit https://github.com/user/repo
|
34 | ```
|
35 |
|
36 | Or you can download from GitLab and BitBucket:
|
37 |
|
38 | ```bash
|
39 | # download from GitLab
|
40 | degit gitlab:user/repo
|
41 | degit git@gitlab.com:user/repo
|
42 | degit https://gitlab.com/user/repo
|
43 |
|
44 | # download from BitBucket
|
45 | degit bitbucket:user/repo
|
46 | degit git@bitbucket.org:user/repo
|
47 | degit https://bitbucket.org/user/repo
|
48 |
|
49 | # download from Sourcehut
|
50 | degit git.sr.ht/user/repo
|
51 | degit git@git.sr.ht:user/repo
|
52 | degit https://git.sr.ht/user/repo
|
53 | ```
|
54 |
|
55 | ### Specify a tag, branch or commit
|
56 |
|
57 | The default branch is `master`.
|
58 |
|
59 | ```bash
|
60 | degit user/repo#dev # branch
|
61 | degit user/repo#v1.2.3 # release tag
|
62 | degit user/repo#1234abcd # commit hash
|
63 | ````
|
64 |
|
65 | ### Create a new folder for the project
|
66 |
|
67 | If the second argument is omitted, the repo will be cloned to the current directory.
|
68 |
|
69 | ```bash
|
70 | degit user/repo my-new-project
|
71 | ```
|
72 |
|
73 | ### Specify a subdirectory
|
74 |
|
75 | To clone a specific subdirectory instead of the entire repo, just add it to the argument:
|
76 |
|
77 | ```bash
|
78 | degit user/repo/subdirectory
|
79 | ```
|
80 |
|
81 | ### HTTPS proxying
|
82 |
|
83 | If you have an `https_proxy` environment variable, Degit will use it.
|
84 |
|
85 | ### Private repositories
|
86 |
|
87 | 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.
|
88 |
|
89 | Note: this clones over SSH, not HTTPS.
|
90 |
|
91 | ### See all options
|
92 |
|
93 | ```bash
|
94 | degit --help
|
95 | ```
|
96 |
|
97 | ## Not supported
|
98 |
|
99 | - Private repositories
|
100 |
|
101 | Pull requests are very welcome!
|
102 |
|
103 | ## Wait, isn't this just `git clone --depth 1`?
|
104 |
|
105 | A few salient differences:
|
106 |
|
107 | - 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
|
108 | - Caching and offline support (if you already have a `.tar.gz` file for a specific commit, you don't need to fetch it again).
|
109 | - Less to type (`degit user/repo` instead of `git clone --depth 1 git@github.com:user/repo`)
|
110 | - Composability via [actions](#actions)
|
111 | - Future capabilities — [interactive mode](https://github.com/Rich-Harris/degit/issues/4), [friendly onboarding and postinstall scripts](https://github.com/Rich-Harris/degit/issues/6)
|
112 |
|
113 | ## JavaScript API
|
114 |
|
115 | You can also use degit inside a Node script:
|
116 |
|
117 | ```js
|
118 | const degit = require('degit');
|
119 |
|
120 | const emitter = degit('user/repo', {
|
121 | cache: true,
|
122 | force: true,
|
123 | verbose: true,
|
124 | });
|
125 |
|
126 | emitter.on('info', info => {
|
127 | console.log(info.message);
|
128 | });
|
129 |
|
130 | emitter.clone('path/to/dest').then(() => {
|
131 | console.log('done');
|
132 | });
|
133 | ```
|
134 |
|
135 | ## Actions
|
136 |
|
137 | 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.
|
138 |
|
139 | ### clone
|
140 |
|
141 | ```json
|
142 | // degit.json
|
143 | [
|
144 | {
|
145 | "action": "clone",
|
146 | "src": "user/another-repo"
|
147 | }
|
148 | ]
|
149 | ```
|
150 |
|
151 | 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.
|
152 |
|
153 | ### remove
|
154 |
|
155 | ```json
|
156 | // degit.json
|
157 | [
|
158 | {
|
159 | "action": "remove",
|
160 | "files": ["LICENSE"]
|
161 | }
|
162 | ]
|
163 | ```
|
164 |
|
165 | Remove a file at the specified path.
|
166 |
|
167 | ## See also
|
168 |
|
169 | - [zel](https://github.com/vutran/zel) by [Vu Tran](https://twitter.com/tranvu)
|
170 | - [gittar](https://github.com/lukeed/gittar) by [Luke Edwards](https://twitter.com/lukeed05)
|
171 |
|
172 | ## License
|
173 |
|
174 | [MIT](LICENSE.md).
|