{"id":17093133,"url":"https://github.com/souvikinator/gh-retrieve","last_synced_at":"2025-10-11T14:31:01.501Z","repository":{"id":57250887,"uuid":"352745619","full_name":"souvikinator/gh-retrieve","owner":"souvikinator","description":"Simple Nodejs module to download any specific directory or sub-directory in a public GitHub repository","archived":false,"fork":false,"pushed_at":"2021-04-12T06:10:15.000Z","size":919,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-12-07T17:54:26.389Z","etag":null,"topics":["file-downloader","gh-retrieve","github","github-directory-download","github-retrieve","hacktober-accepted","hacktoberfest","hactoberfest2021","javascript","nodejs","nodejs-modules","npm","npm-package"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/souvikinator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-29T18:29:36.000Z","updated_at":"2023-09-13T13:32:24.000Z","dependencies_parsed_at":"2022-08-24T16:52:09.418Z","dependency_job_id":null,"html_url":"https://github.com/souvikinator/gh-retrieve","commit_stats":null,"previous_names":["darthcucumber/gh-retrieve"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/souvikinator%2Fgh-retrieve","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/souvikinator%2Fgh-retrieve/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/souvikinator%2Fgh-retrieve/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/souvikinator%2Fgh-retrieve/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/souvikinator","download_url":"https://codeload.github.com/souvikinator/gh-retrieve/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236102469,"owners_count":19095201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["file-downloader","gh-retrieve","github","github-directory-download","github-retrieve","hacktober-accepted","hacktoberfest","hactoberfest2021","javascript","nodejs","nodejs-modules","npm","npm-package"],"created_at":"2024-10-14T14:04:51.682Z","updated_at":"2025-10-11T14:30:56.188Z","avatar_url":"https://github.com/souvikinator.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gh-retrieve\n\nNodejs module to download/retrieve a specific directory or sub-directory from a public GitHub repository\n\n**NOTE:** since it uses github API, making more than 60 request may give 403,433 or 404 error so simply wait for an hour.\n\nAny contribution is appreciated.\nplease do report bugs if you find any over here: [issues](https://github.com/DarthCucumber/gh-retrieve/issues)\n\n- **v1.1.2**: minor bug fix\n\n- **v1.1.1**:\n\n  - **Breaking changes**\n\n  now users have the choices to select the type of download.\n\n  - **recursiveDownload(options)**: doesn't require github to the installed in the users device and also is limited by github api limits i.e 60 requests/hour a repo.\n\n  - **sparseDownload(options)**: requires git to be installed and it maintains the git workflow of the target repository but downloading only the target directory.\n\n  choice is yours ;)\n\n- **v1.0.2**: previous fix lead to bug, not downloading file contents. Fixed now\n\n- **v1.0.1**: fixed minor directory bug\n\n## Installation\n\n```js\nnpm install gh-retrieve\n```\n\n## Demo:\n\n### Using recursiveDownload()\n\n```js\nconst { recusiveDownload } = require(\"gh-retrieve\");\n\nrecursiveDownload({\n  author: \"DarthCucumber\", //repository owner\n  repo: \"gofuzz\", //repository name\n  targetdir: \"pkg\", //target directory to download\n  outdir: \"test\", //directory to download in\n}).catch((err) =\u003e {\n  console.log(err.stack);\n});\n```\n\nand boom! you have the files downloaded.\n\n### using sparseDownload()\n\n```js\nconst { sparseDownload } = require(\"gh-retrieve\");\n\nsparseDownload({\n  //can use https clone url as well if ssh is not set up\n  cloneurl: \"git@github.com:DarthCucumber/gofuzz.git\",\n  targetdir: \"pkg\",\n  outdir: \"../test\",\n  branch: \"master\",\n}).catch((err) =\u003e {\n  console.log(err.stack);\n});\n```\n\nto download any sub directory, just enter the path like so (works for both **recursiveDownload** and **sparseDownload**):\n\n```js\nconst { sparseDownload } = require(\"gh-retrieve\");\n\nsparseDownload({\n  //can use http clone url as well instead of SSH\n  cloneurl: \"git@github.com:DarthCucumber/gofuzz.git\",\n  targetdir: \"pkg/data\",\n  outdir: \"../test\",\n  branch: \"master\",\n}).catch((err) =\u003e {\n  console.log(err.stack);\n});\n```\n\nhow to use with [ora](https://www.npmjs.com/package/ora) with **gh-retrieve**?\n\n```js\nconst { recusiveDownload } = require(\"gh-retrieve\");\nconst ora = require(\"ora\");\n\nconst spinner = ora(\"downloading files...\").start();\n\nrecursiveDownload({\n  author: \"DarthCucumber\", //repository owner\n  repo: \"gofuzz\", //repository name\n  targetdir: \"pkg\", //target directory to download\n  outdir: \"test\", //directory to download in\n})\n  .then(() =\u003e {\n    spinner.succeed(\"download complete.\");\n  })\n  .catch((err) =\u003e {\n    spinner.fail(err.message);\n    console.log(err.stack);\n  });\n```\n\n### API\n\n### recusiveDownload(options)\n\n**NOTE:** options argument for both *recusiveDownload* and *sparseDownload* are different.\n\ntakes options object as argument.\n\n**option** consists of following properties:\n\n```js\n{\n  author: string, //required\n  repo: string, //required\n  targetdir: string, //required\n  branch: string, //optional\n  outdir: string //optional\n}\n```\n\nUsing this module's repo as example. `https://github.com/DarthCucumber/gh-retrieve`\n\n- **author** takes username of the repository owner _(required)_\n\nexample: **DarthCucumber** is **author** in the example url\n\n- **repo** takes the repository name from where you want to download a specific directory _(required)_\n\nexample: **gh-retrieve** is **repo**\n\n- **dir** takes in target directory you want to download. _(required)_\n\n- **branch** takes in branch of the repo _(optional)_\n\n- **outdir** takes in output directory path where your files will get downloaded. (default: current directory) _(optional)_\n\n### sparseDownload(options)\n\ntakes options object as argument.\n\n**option** consists of following properties:\n\n```js\n{\n  cloneurl: string,\n  targetdir: string,\n  outdir: string,\n  branch: string,\n}\n```\n\n**All options are required**\n\n**cloneurl** is the url used for cloning a repo. Ex: https://github.com/DarthCucumber/gh-retrieve.git\n\n**targetdir** is the directory name you want to download\n\n**outdir** is the directory where you want to download the target directory in your workspace.\n\n*NOTE:* make sure you don't set **outdir** as an existing git repo.\n\n**branch:** takes the repository branch.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsouvikinator%2Fgh-retrieve","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsouvikinator%2Fgh-retrieve","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsouvikinator%2Fgh-retrieve/lists"}