Fork and Pull
The fork and pull model popularized by GitHub is the most common way to use gg. When using this model, the project has a primary repository that only the maintainers of the project have write access to. Contributors make changes by sharing a cloned repository (called the fork) with new branches. Contributors send pull requests to maintainers, who then review the code and merge in the changes.
When setting up your working copy, you will first clone the repository as
normal, then add your fork as another remote. gg respects the
remote.pushDefault Git configuration option on pushes, which reduces the
amount of typing you need to push your commits.
gg clone https://example.com/foo.git cd foo git remote add myfork https://example.com/myfork/foo.git git config remote.pushDefault myfork
Replace the URLs and the name
myfork above as needed.
Every change should be on a separate branch.
gg branch will automatically
handle setting the branch’s upstream. If you configure your working copy as
detailed in the Cloning section,
gg push will automatically push your local
branch to your fork with the same branch name.
gg branch myfeature # hack hack hack gg commit -m "Added a feature" gg push --new-branch -r myfeature
If you’re on GitHub, you can use
gg requestpull (commonly abbreviated to
pr) to create a pull request from the command line.
To make changes after code review, simply push more commits to your branch and
gg push again.
# hack hack hack gg commit -m "Addressed code review comments" gg push
(Your pull request will automatically be updated; there’s no need to create it again.)
Syncing Your Work with the Upstream Branch
If the upstream branch (e.g.
main) changed, then you can use
to merge in commits.
gg pull && gg merge
If there are no conflicts or test breakages, you can run
gg commit to commit
Syncing Your Work with your Fork’s Branch
If your fork’s branch changes (for example, if a maintainer adds commits), then
first you need to download the new commits from your fork using
gg pull -r CURRENT_BRANCH myfork
CURRENT_BRANCH with the name of your current branch and
the name of the remote you added in the Cloning section.
Once you’ve downloaded the commits, you will need to either merge or rebase your local commits. Merging will create a new commit that merges the two streams of work, whereas rebasing will recreate your changes on top of the downloaded commits.
To create a merge commit:
gg merge FETCH_HEAD # Resolve any conflicts, run tests. gg commit
Or to rebase your commits onto the downloaded changes:
gg rebase --base=FETCH_HEAD --dst=FETCH_HEAD
Switching Among Changes
You can list all of your branches with:
You can use
gg update to switch to a different branch.
gg update myfeature gg update main