{"id":15290437,"url":"https://github.com/npm/git","last_synced_at":"2025-05-15T04:08:16.824Z","repository":{"id":40524232,"uuid":"246167265","full_name":"npm/git","owner":"npm","description":"a util for spawning git from npm CLI contexts","archived":false,"fork":false,"pushed_at":"2025-02-18T21:34:37.000Z","size":401,"stargazers_count":69,"open_issues_count":3,"forks_count":16,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-05-14T01:09:02.593Z","etag":null,"topics":["npm-cli"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/npm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-09T23:57:08.000Z","updated_at":"2025-05-08T12:38:30.000Z","dependencies_parsed_at":"2024-04-20T22:52:56.824Z","dependency_job_id":"ba38a624-712c-40b4-aef9-c015c96d068a","html_url":"https://github.com/npm/git","commit_stats":{"total_commits":183,"total_committers":14,"mean_commits":"13.071428571428571","dds":0.6939890710382514,"last_synced_commit":"0fc4208897ed29c0651f17d8e7593827110d1ea7"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Fgit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Fgit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Fgit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Fgit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/npm","download_url":"https://codeload.github.com/npm/git/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254270656,"owners_count":22042860,"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":["npm-cli"],"created_at":"2024-09-30T16:08:11.355Z","updated_at":"2025-05-15T04:08:11.812Z","avatar_url":"https://github.com/npm.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @npmcli/git\n\nA utility for spawning git from npm CLI contexts.\n\nThis is _not_ an implementation of git itself, it's just a thing that\nspawns child processes to tell the system git CLI implementation to do\nstuff.\n\n## USAGE\n\n```js\nconst git = require('@npmcli/git')\ngit.clone('git://foo/bar.git', 'some-branch', 'some-path', opts) // clone a repo\n  .then(() =\u003e git.spawn(['checkout', 'some-branch'], {cwd: 'bar'}))\n  .then(() =\u003e git.spawn(['you get the idea']))\n```\n\n## API\n\nMost methods take an options object.  Options are described below.\n\n### `git.spawn(args, opts = {})`\n\nLaunch a `git` subprocess with the arguments specified.\n\nAll the other functions call this one at some point.\n\nProcesses are launched using\n[`@npmcli/promise-spawn`](http://npm.im/@npmcli/promise-spawn), with the\n`stdioString: true` option enabled by default, since git output is\ngenerally in readable string format.\n\nReturn value is a `Promise` that resolves to a result object with `{cmd,\nargs, code, signal, stdout, stderr}` members, or rejects with an error with\nthe same fields, passed back from\n[`@npmcli/promise-spawn`](http://npm.im/@npmcli/promise-spawn).\n\n### `git.clone(repo, ref = 'HEAD', target = null, opts = {})` -\u003e `Promise\u003csha String\u003e`\n\nClone the repository into `target` path (or the default path for the name\nof the repository), checking out `ref`.\n\nReturn value is the sha of the current HEAD in the locally cloned\nrepository.\n\nIn lieu of a specific `ref`, you may also pass in a `spec` option, which is\na [`npm-package-arg`](http://npm.im/npm-package-arg) object for a `git`\npackage dependency reference.  In this way, you can select SemVer tags\nwithin a range, or any git committish value.  For example:\n\n```js\nconst npa = require('npm-package-arg')\ngit.clone('git@github.com:npm/git.git', '', null, {\n  spec: npa('github:npm/git#semver:1.x'),\n})\n\n// only gitRange and gitCommittish are relevant, so this works, too\ngit.clone('git@github.com:npm/git.git', null, null, {\n  spec: { gitRange: '1.x' }\n})\n```\n\nThis will automatically do a shallow `--depth=1` clone on any hosts that\nare known to support it.  To force a shallow or deep clone, you can set the\n`gitShallow` option to `true` or `false` respectively.\n\n### `git.revs(repo, opts = {})` -\u003e `Promise\u003crev doc Object\u003e`\n\nFetch a representation of all of the named references in a given\nrepository.  The resulting doc is intentionally somewhat\n[packument](https://www.npmjs.com/package/pacote#packuments)-like, so that\ngit semver ranges can be applied using the same\n[`npm-pick-manifest`](http://npm.im/npm-pick-manifest) logic.\n\nThe resulting object looks like:\n\n```js\nrevs = {\n  versions: {\n    // all semver-looking tags go in here...\n    // version: { sha, ref, rawRef, type }\n    '1.0.0': {\n      sha: '1bc5fba3353f8e1b56493b266bc459276ab23139',\n      ref: 'v1.0.0',\n      rawRef: 'refs/tags/v1.0.0',\n      type: 'tag',\n    },\n  },\n  'dist-tags': {\n    HEAD: '1.0.0',\n    latest: '1.0.0',\n  },\n  refs: {\n    // all the advertised refs that can be cloned down remotely\n    HEAD: { sha, ref, rawRef, type: 'head' },\n    master: { ... },\n    'v1.0.0': { ... },\n    'refs/tags/v1.0.0': { ... },\n  },\n  shas: {\n    // all named shas referenced above\n    // sha: [list, of, refs]\n    '6b2501f9183a1753027a9bf89a184b7d3d4602c7': [\n      'HEAD',\n      'master',\n      'refs/heads/master',\n    ],\n    '1bc5fba3353f8e1b56493b266bc459276ab23139': [ 'v1.0.0', 'refs/tags/v1.0.0' ],\n  },\n}\n```\n\n### `git.is(opts)` -\u003e `Promise\u003cBoolean\u003e`\n\nResolve to `true` if the path argument refers to the root of a git\nrepository.\n\nIt does this by looking for a file in `${path}/.git/index`, which is not an\nairtight indicator, but at least avoids being fooled by an empty directory\nor a file named `.git`.\n\n### `git.find(opts)` -\u003e `Promise\u003cString | null\u003e`\n\nGiven a path, walk up the file system tree until a git repo working\ndirectory is found.  Since this calls `stat` a bunch of times, it's\nprobably best to only call it if you're reasonably sure you're likely to be\nin a git project somewhere. Pass in `opts.root` to stop checking at that\ndirectory.\n\nResolves to `null` if not in a git project.\n\n### `git.isClean(opts = {})` -\u003e `Promise\u003cBoolean\u003e`\n\nReturn true if in a git dir, and that git dir is free of changes.  This\nwill resolve `true` if the git working dir is clean, or `false` if not, and\nreject if the path is not within a git directory or some other error\noccurs.\n\n## OPTIONS\n\n- `retry` An object to configure retry behavior for transient network\n  errors with exponential backoff.\n  - `retries`: Defaults to `opts.fetchRetries` or 2\n  - `factor`: Defaults to `opts.fetchRetryFactor` or 10\n  - `maxTimeout`: Defaults to `opts.fetchRetryMaxtimeout` or 60000\n  - `minTimeout`: Defaults to `opts.fetchRetryMintimeout` or 1000\n- `git` Path to the `git` binary to use.  Will look up the first `git` in\n  the `PATH` if not specified.\n- `spec` The [`npm-package-arg`](http://npm.im/npm-package-arg) specifier\n  object for the thing being fetched (if relevant).\n- `fakePlatform` set to a fake value of `process.platform` to use.  (Just\n  for testing `win32` behavior on Unix, and vice versa.)\n- `cwd` The current working dir for the git command.  Particularly for\n  `find` and `is` and `isClean`, it's good to know that this defaults to\n  `process.cwd()`, as one might expect.\n- Any other options that can be passed to\n  [`@npmcli/promise-spawn`](http://npm.im/@npmcli/promise-spawn), or\n  `child_process.spawn()`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpm%2Fgit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnpm%2Fgit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpm%2Fgit/lists"}