1 | # download-git-repo
|
2 |
|
3 | Download and extract a git repository (GitHub, GitLab, Bitbucket) from node.
|
4 |
|
5 | ## Installation
|
6 |
|
7 | $ npm install download-git-repo
|
8 |
|
9 | ## API
|
10 |
|
11 | ### download(repository, destination, options, callback)
|
12 |
|
13 | Download a git `repository` to a `destination` folder with `options`, and `callback`.
|
14 |
|
15 | #### repository
|
16 | The shorthand repository string to download the repository from:
|
17 |
|
18 | - **GitHub** - `github:owner/name` or simply `owner/name`
|
19 | - **GitLab** - `gitlab:owner/name`
|
20 | - **Bitbucket** - `bitbucket:owner/name`
|
21 |
|
22 | The `repository` parameter defaults to the `master` branch, but you can specify a branch or tag as a URL fragment like `owner/name#my-branch`.
|
23 | In addition to specifying the type of where to download, you can also specify a custom origin like `gitlab:custom.com:owner/name`.
|
24 | Custom origin will default to `https` or `git@` for http and clone downloads respectively, unless protocol is specified.
|
25 | Feel free to submit an issue or pull request for additional origin options.
|
26 |
|
27 | In addition to having the shorthand for supported git hosts, you can also hit a repository directly with:
|
28 |
|
29 | - **Direct** - `direct:url`
|
30 |
|
31 | This will bypass the shorthand normalizer and pass `url` directly.
|
32 | If using `direct` without clone, you must pass the full url to the zip file, including paths to branches if needed.
|
33 | If using `direct` with clone, you must pass the full url to the git repo and you can specify a branch like `direct:url#my-branch`.
|
34 |
|
35 | #### destination
|
36 | The file path to download the repository to.
|
37 |
|
38 | #### options
|
39 | An optional options object parameter with download options. Options include:
|
40 |
|
41 | - `clone` - boolean default `false` - If true use `git clone` instead of an http download. While this can be a bit slower, it does allow private repositories to be used if the appropriate SSH keys are setup.
|
42 | - All other options (`proxy`, `headers`, `filter`, etc.) will be passed down accordingly and may override defaults
|
43 | - Additional download options: https://github.com/kevva/download#options
|
44 | - Additional clone options: https://github.com/jaz303/git-clone#clonerepo-targetpath-options-cb
|
45 |
|
46 | #### callback
|
47 | The callback function as `function (err)`.
|
48 |
|
49 | ## Examples
|
50 | ### Shorthand
|
51 | Using http download from Github repository at master.
|
52 | ```javascript
|
53 | download('flipxfx/download-git-repo-fixture', 'test/tmp', function (err) {
|
54 | console.log(err ? 'Error' : 'Success')
|
55 | })
|
56 | ```
|
57 |
|
58 | Using git clone from Bitbucket repository at my-branch.
|
59 | ```javascript
|
60 | download('bitbucket:flipxfx/download-git-repo-fixture#my-branch', 'test/tmp', { clone: true }, function (err) {
|
61 | console.log(err ? 'Error' : 'Success')
|
62 | })
|
63 | ```
|
64 |
|
65 | Using http download from GitLab repository with custom origin and token.
|
66 | ```javascript
|
67 | download('gitlab:mygitlab.com:flipxfx/download-git-repo-fixture#my-branch', 'test/tmp', { headers: { 'PRIVATE-TOKEN': '1234' } } function (err) {
|
68 | console.log(err ? 'Error' : 'Success')
|
69 | })
|
70 | ```
|
71 |
|
72 | Using git clone from GitLab repository with custom origin and protocol.
|
73 | Note that the repository type (`github`, `gitlab` etc.) is not required if cloning from a custom origin.
|
74 | ```javascript
|
75 | download('https://mygitlab.com:flipxfx/download-git-repo-fixture#my-branch', 'test/tmp', { clone: true }, function (err) {
|
76 | console.log(err ? 'Error' : 'Success')
|
77 | })
|
78 | ```
|
79 |
|
80 | ### Direct
|
81 | Using http download from direct url.
|
82 | ```javascript
|
83 | download('direct:https://gitlab.com/flipxfx/download-git-repo-fixture/repository/archive.zip', 'test/tmp', function (err) {
|
84 | console.log(err ? 'Error' : 'Success')
|
85 | })
|
86 | ```
|
87 |
|
88 | Using git clone from direct url at master.
|
89 | ```javascript
|
90 | download('direct:https://gitlab.com/flipxfx/download-git-repo-fixture.git', 'test/tmp', { clone: true }, function (err) {
|
91 | console.log(err ? 'Error' : 'Success')
|
92 | })
|
93 | ```
|
94 |
|
95 | Using git clone from direct url at my-branch.
|
96 | ```javascript
|
97 | download('direct:https://gitlab.com/flipxfx/download-git-repo-fixture.git#my-branch', 'test/tmp', { clone: true }, function (err) {
|
98 | console.log(err ? 'Error' : 'Success')
|
99 | })
|
100 | ```
|
101 |
|
102 | ## License
|
103 |
|
104 | MIT
|
105 |
|