How to sync fork with master repo?

[ktyle]

Now that we've merged several PRs from various forks, I would like to sync up my fork with ProjectPythia's. How can I do that?

[erogluorhan]

This could help: Syncing a fork

Note: If git fetch upstream gives you an error, you may first need to git remote add upstream https://github.com/ProjectPythia/pythia-foundations (i.e. the original repo URL).

[brian-rose]

In the climlab documentation, we point readers to these instructions for Forking a repo and setting the upstream remote.

In my understanding, best practice is to keep your local main branch clean at all times and do all your edits on separate branches. Then you can always keep your local main branch in sync with the upstream version by doing

git pull upstream main

and then push the latest version up to your GitHub fork with

git push origin main

In that way both your local main and your GitHub fork of main are always consistent with the upstream main.

@dopplershift wrote some useful comments about not editing your main branch over at #25 (comment)

[dopplershift]

A few other helpful tips:

1. I find origin really unclear (and to a much less extent upstream). So I always rename origin to me. You can rename a remote with git remote rename origin me
2. I usually have main set to track the upstream main so that a git pull with main as the active branch always does the right thing. You can set the upstream for a branch with git branch --set-upstream-to upstream/main main

If I'm being honest, though, I never bother updating main on my remote fork. It doesn't serve much of a purpose (the latest commit on master on my MetPy fork is from August 2018). It's only the local copy of main that matters. My cycle is:

1. Grab latest changes (with main branch checked out): git pull
2. Checkout feature branch to work: git checkout -b my-next-feature
3. Work and commit
4. Push to github git push -u me my-next-feature (this sets my local feature branch to track the remote branch on my fork)
5. Make PR
6. Do more work and commit
7. Push to github git push
8. PR merged, click "delete branch" on PR.
9. Checkout and update main: git checkout main and git pull
10. Delete local branch: git branch -d my-next-feature
11. Clear out local reference to deleted remote branch: git remote prune me

[brian-rose]

I think we should take @dopplershift's workflow here and write it up as a "best practice" for our contributor's guide.

[brian-rose]

Maybe in the short term we should focus on writing this stuff up as a more clear Contributor's Guide for the team itself. This could gracefully transition into a full-fledged tutorial on how to use git and do Pull Requests.

[ktyle]

Thanks to you both, @erogluorhan and @brian-rose ... the steps Orhan described worked perfectly. I was thinking the same thing that this would be an essential add to the Contributor's Guide ... so I will plan on submitting a PR for that in the next few days.