From 5dacec4950a3746310bb30704417a792302b044a Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Thu, 23 Jun 2022 10:18:41 -0700 Subject: [PATCH] More about syning with upstream --- workflows-upstream-changes-into-fork.Rmd | 35 ++++++++++++++++++------ 1 file changed, 26 insertions(+), 9 deletions(-) diff --git a/workflows-upstream-changes-into-fork.Rmd b/workflows-upstream-changes-into-fork.Rmd index 320d47b..783cfb2 100644 --- a/workflows-upstream-changes-into-fork.Rmd +++ b/workflows-upstream-changes-into-fork.Rmd @@ -175,17 +175,34 @@ The official GitHub documentation for this is [Syncing a fork from the web UI](h Navigate to the main page of your fork `YOU/REPO`, i.e. your primary repo which is configured as the `origin` remote. -Towards the upper right corner, you will see "Fetch upstream". -Click this and then click "Fetch and merge". +At the top you'll see some information on how the state of `main` in your fork relates to `main` in the source repo, similar to what we see with `git status` in the alternative approach above. +Ideally you will see something like: + +``` +This branch is 2 commits behind OWNER:main. +``` + +which indicates you can sync up in the ideal fast-forward sense. + +If you see something like this: + +``` +This branch is 1 commit ahead, 2 commits behind OWNER:main. +``` + +this is a sign that you have made some regrettable choices. + +I recommend that you [never make your own commits to the default branch of a fork](#fork-dont-touch-main) or to any branch that you don't effectively (co-)own. +However, if you have already done so, we explain how to fix the problem in [Um, what if I did touch `main`?](#touched-main). + +Once you are ready to proceed, click "Fetch upstream" in the upper right corner and then "Fetch and merge". Upon success, the main page of `YOU/REPO` shows something like > This branch is up to date with `OWNER/REPO:main`. -If this does not "just work", it probably means you have made commits on the default branch of your fork, which we [strongly advise against](#fork-dont-touch-main). -I believe GitHub then gives you the option of bringing the `upstream` changes into your fork as a pull request. -Alternatively, you could back out and straighten out the history of the default branch, using the instructions below. -Then you could do a force push to `origin` and try the sync again. -You could even consider deleting your fork and local repo and making a fresh start with [Fork and clone](fork-and-clone). +If you have made commits on the default branch of your fork, which we [strongly advise against](#fork-dont-touch-main), this can result in a merge commit (or even merge conflicts). +If you are suffering due to commits you've made on `main` and it's beyond the help we describe below, consider deleting your fork and local repo and making a fresh start with [Fork and clone](fork-and-clone). +Live and learn. Once you have successfully synced the default branch of `YOU/REPO` with the default branch of `OWNER/REPO`, you probably want to do the same for your local repo. Since they are synced, you can pull from either `upstream` or `origin`. @@ -248,12 +265,12 @@ See *future link about time travel* for more support. -Your `main` branch now reflects (a subset) of the history of `OWNER/REPO`. +The history of your `main` branch is now compatible with its history in `OWNER/REPO`. The instructions above for pulling changes from `upstream` should now work. A fast-forward-only pull should succeed. ``` bash -git pull upstream --ff-only +git pull upstream main --ff-only ``` And now your local history for `main` should match that in the source repo: