With the GitHub CLI, after `gh repo fork acme/widgets --clone`, which remotes exist and which repository does `gh pr create` target?
answer
- two remotes, two roles
- your copy versus the parent
- the default repository gh queries
- push first, or name the head
basics
~10 sorigin points at your fork and upstream at acme/widgets, which gh marks as the default repository; gh pr create therefore opens the pull request against acme/widgets, using a head branch pushed to your fork.
solid answer
~40 s`gh repo fork acme/widgets --clone` creates the fork under your account (or reuses it if it exists), clones it so `origin` is your fork, adds `upstream` for `acme/widgets`, fetches it and marks it as the **default repository**. That default is what `gh pr`, `gh issue`, `gh release` and `gh run` query, so `gh pr create` opens the pull request on `acme/widgets` with your fork's branch as the head. The base branch is `--base`, else the branch's `gh-merge-base` Git config, else the repository's default branch. If the branch is not pushed yet, gh prompts for where to push; without a terminal it aborts unless you push first or pass `--head`. `gh repo clone` of a fork sets up the same `upstream` remote, and `--no-upstream` (gh 2.88.0) skips it.
go deeper
Recall the layout: origin is your fork, upstream is the parent, and gh pr create opens the pull request on the parent.
Explain the default repository and how gh pr create picks base, head, title and body, including the non-interactive rules for pushing and filling.
Diagnose a pull request opened in the wrong repository or a CI job that cannot create one, using gh repo set-default, --head and the gh-merge-base config.
Weigh a fork-based contribution model against shared-repository branches for a team, and what each means for gh's defaults and for who can push to a pull request.
## The fork workflow in one command A **fork** is your own server-side copy of someone else's repository. Contributors without write access push their branches to the fork and open pull requests back to the original, called the **parent** or **upstream**. Setting that up by hand takes a fork in the browser, a clone, a second remote and a fetch. The GitHub CLI does all of it in one command: ```bash gh repo fork acme/widgets --clone ``` It does the following, in order: 1. **Creates the fork** under your account. `--org <name>` puts it in an organisation instead, `--fork-name` renames it, and `--default-branch-only` copies only the default branch. If you already have a fork, gh reports that it already exists and reuses it. 2. **Clones the fork**, so `origin` points at `alice/widgets`, your copy. 3. **Adds a remote named `upstream`** for `acme/widgets` and fetches it. 4. **Marks `upstream` as the default repository** and prints a note pointing at `gh repo set-default --help`. ## Why the default repository matters A clone with two remotes is ambiguous: when you type `gh issue list`, which repository's issues do you mean? gh settles it with the **default repository**, the remote marked for gh to query. According to the help for `gh repo set-default`, gh uses it for: - viewing and creating pull requests; - viewing and creating issues; - viewing and creating releases; - working with GitHub Actions runs. After a fork-and-clone the default is the parent. `gh issue list` shows `acme/widgets` issues, and `gh pr create` opens the pull request in `acme/widgets`. Check it with `gh repo set-default --view`, or change it with `gh repo set-default origin` when you really mean your fork. Repository and environment secrets are the stated exception: gh does not use the default repository to manage them. | Command | Remote layout afterwards | Default repository | |---|---|---| | `gh repo fork acme/widgets --clone` | `origin` = your fork, `upstream` = parent | parent | | `gh repo clone alice/widgets` (a fork) | `origin` = fork, `upstream` = parent | parent | | `gh repo clone alice/widgets --no-upstream` | `origin` only | the fork (`origin`) | | `gh repo fork --remote` inside a clone of the parent | old `origin` renamed to `upstream`, fork added as `origin` | see `gh repo set-default --view` | `gh repo clone` also accepts `--upstream-remote-name <name>` (the value `@owner` names the remote after the parent's owner). `--no-upstream` was added in **gh 2.88.0**. Running `gh repo fork` inside an existing clone of the parent offers to add a remote. With `--remote-name` you pick its name, and gh then does not rename your existing `origin`. ## What gh pr create does next On a feature branch in that clone, `gh pr create` works out three things. **The base.** The repository is the default repository. The branch is `--base` / `-B` if given, else the `gh-merge-base` value in the branch's Git config (`git config branch.<current>.gh-merge-base release/2.x`), else the repository's default branch. **The head.** If the branch is already pushed to a remote, gh uses it. If it is not, then: - in a terminal, gh asks where to push the branch, listing the remotes you can push to and, if you have no fork yet, offering to create one. A fork created this way gets only the parent's default branch; - without a terminal, as in a CI job, it stops with an error telling you to push the branch first or use `--head`; - `--head` / `-H` names the head branch outright (`<user>:<branch>` selects a user's fork) and skips any push or fork step. **Title and body.** - `--fill`: with one commit, the commit's subject and body; with several, the branch name made readable as the title and a bullet list of commit subjects as the body. - `--fill-first`: the first commit's subject and body. `--fill-verbose`: every commit's subject and body. - `--title` / `--body` override whatever a fill flag produced. - Without a terminal you must give `--title` and `--body` or one of the fill flags. **Other useful flags.** `--draft` opens the pull request as a draft. `--reviewer`, `--assignee`, `--label` and `--milestone` set metadata. `--no-maintainer-edit` stops users with write access to the base repository from pushing to your head branch. `--dry-run` prints what would be created, though the help warns it may still push Git changes. When it succeeds, `gh pr create` prints the new pull request's URL. ## Where the edges are - A pull request body that says `Closes #123` closes the issue on merge. That is GitHub's keyword behaviour, covered with issues and pull requests, not a gh feature. - Keeping your fork's default branch current is a Git or `gh repo sync` matter. It is separate from opening the pull request. - If `gh pr create` opens the pull request in the wrong repository, the first thing to check is the default repository, not the remotes.
- `gh pr create` opened the pull request against your fork instead of the parent. What do you check?The default repository. `gh repo set-default --view` shows which repository gh queries; if it is your fork (for example after `gh repo clone --no-upstream`, or after someone ran `gh repo set-default origin`), run `gh repo set-default acme/widgets`, or pass `--repo acme/widgets` for a single command.
- How do you make every pull request from a long-lived branch target `release/2.x` without typing `--base` each time?Set the branch's `gh-merge-base` Git config: `git config branch.<branch>.gh-merge-base release/2.x`. `gh pr create` uses it whenever `--base` is not given, and falls back to the repository's default branch otherwise.
- gh pr create always targets whatever repository origin points at
- gh repo fork --clone leaves you with a single remote for the fork
- gh pr create --dry-run is guaranteed to make no git changes
- --fill always uses the latest commit's message as the pull request title
- In a CI job gh pr create pushes the branch for you automatically
Assumes gh 2.102; gh repo clone gained --no-upstream in gh 2.88.0 to skip the upstream remote when cloning a fork.