|
| 1 | +--- |
| 2 | +title: push |
| 3 | +sidebar_label: push |
| 4 | +id: version-0.77.0-push |
| 5 | +original_id: push |
| 6 | +--- |
| 7 | + |
| 8 | +Push a branch or tag |
| 9 | + |
| 10 | +| param | type [= default] | description | |
| 11 | +| -------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------- | |
| 12 | +| core | string = 'default' | The plugin core identifier to use for plugin injection | |
| 13 | +| fs [deprecated] | FileSystem | The filesystem containing the git repo. Overrides the fs provided by the [plugin system](./plugin_fs.md). | |
| 14 | +| dir | string | The [working tree](dir-vs-gitdir.md) directory path | |
| 15 | +| **gitdir** | string = join(dir,'.git') | The [git directory](dir-vs-gitdir.md) path | |
| 16 | +| ref | string | Which branch to push. By default this is the currently checked out branch. | |
| 17 | +| remoteRef | string | The name of the receiving branch on the remote. By default this is the same as `ref`. (See note below) | |
| 18 | +| remote | string | If URL is not specified, determines which remote to use. | |
| 19 | +| force | boolean = false | If true, behaves the same as `git push --force` | |
| 20 | +| delete | boolean = false | If true, delete the remote ref | |
| 21 | +| noGitSuffix | boolean = false | If true, do not auto-append a `.git` suffix to the `url`. (**AWS CodeCommit needs this option**) | |
| 22 | +| url | string | The URL of the remote git server. The default is the value set in the git config for that remote. | |
| 23 | +| corsProxy | string | Optional [CORS proxy](https://www.npmjs.com/%40isomorphic-git/cors-proxy). Overrides value in repo config. | |
| 24 | +| username | string | See the [Authentication](./authentication.html) documentation | |
| 25 | +| password | string | See the [Authentication](./authentication.html) documentation | |
| 26 | +| token | string | See the [Authentication](./authentication.html) documentation | |
| 27 | +| oauth2format | string | See the [Authentication](./authentication.html) documentation | |
| 28 | +| headers | object | Additional headers to include in HTTP requests, similar to git's `extraHeader` config | |
| 29 | +| autoTranslateSSH | boolean | Attempt to automatically translate SSH remotes into HTTP equivalents | |
| 30 | +| emitter [deprecated] | EventEmitter | Overrides the emitter set via the ['emitter' plugin](./plugin_emitter.md). | |
| 31 | +| emitterPrefix | string = '' | Scope emitted events by prepending `emitterPrefix` to the event name. | |
| 32 | +| return | Promise\<PushResponse\> | Resolves successfully when push completes with a detailed description of the operation from the server. | |
| 33 | + |
| 34 | +Returns an object with a schema like this: |
| 35 | + |
| 36 | +```ts |
| 37 | +type PushResponse = { |
| 38 | + ok?: Array<string>; |
| 39 | + errors?: Array<string>; |
| 40 | + headers?: object; |
| 41 | +} |
| 42 | +``` |
| 43 | +
|
| 44 | +> *Note:* The behavior of `remoteRef` is reasonable but not the _correct_ behavior. It _should_ be using the configured remote tracking branch! TODO: I need to fix this |
| 45 | +
|
| 46 | +The push command returns an object that describes the result of the attempted push operation. |
| 47 | +*Notes:* If there were no errors, then there will be no `errors` property. There can be a mix of `ok` messages and `errors` messages. |
| 48 | +
|
| 49 | +| param | type [= default] | description | |
| 50 | +| ------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 51 | +| ok | Array\<string\> | The first item is "unpack" if the overall operation was successful. The remaining items are the names of refs that were updated successfully. | |
| 52 | +| errors | Array\<string\> | If the overall operation threw and error, the first item will be "unpack {Overall error message}". The remaining items are individual refs that failed to be updated in the format "{ref name} {error message}". | |
| 53 | +
|
| 54 | +To monitor progress events, see the documentation for the [`'emitter'` plugin](./plugin_emitter.md). |
| 55 | +
|
| 56 | +Example Code: |
| 57 | +
|
| 58 | +```js live |
| 59 | +let pushResponse = await git.push({ |
| 60 | + dir: '$input((/))', |
| 61 | + remote: '$input((origin))', |
| 62 | + ref: '$input((master))', |
| 63 | + token: $input((process.env.GITHUB_TOKEN)), |
| 64 | +}) |
| 65 | +console.log(pushResponse) |
| 66 | +``` |
| 67 | + |
| 68 | +<script> |
| 69 | +(function rewriteEditLink() { |
| 70 | + const el = document.querySelector('a.edit-page-link.button'); |
| 71 | + if (el) { |
| 72 | + el.href = 'https://github.com/isomorphic-git/isomorphic-git/edit/master/src/commands/push.js'; |
| 73 | + } |
| 74 | +})(); |
| 75 | +</script> |
0 commit comments