degit/README.md

# 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

### Basics

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
```


### Specify a tag, branch or commit

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
```


### Create a new folder for the project

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

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


### See all options

```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](#actions)
* 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)


## 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. Currently, there are two actions — `clone` and `remove`.

### clone

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

This will clone the contents of `user/another-repo` on top of the existing repo. The cloned repo can contain its own `degit.json` actions.

### remove

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

Additional actions may be added in future.


## See also

* [zel](https://github.com/vutran/zel) by [Vu Tran](https://twitter.com/tranvu)
* [gittar](https://github.com/lukeed/gittar) by [Luke Edwards](https://twitter.com/lukeed05)


## License

[MIT](LICENSE).