3152bf572b
* Add "Resynchronizing an Out-of-Sync Git Branch" doc
* Update (Git) Best Practices doc title and filename
* Rename Branch Resync doc
* fork Best Practices doc into multiple files
* Add the doc list to Git Best Practices doc
* Update sidebar
* Update internal references
* Update sidebar - add subsection
* Update Your Fork's Master page title
* title case on Git Best Practices main doc
* ... and in the Resynchronizing a Branch doc
* Please read Part 1
I worked really hard on this, okay?
* Please use branches, too.
* suggestions by mtei
* change note about adding multiple files
* note that the name given the remote repo is arbitrary
* suggestions by fauxpark
* Git Best Practices -> Best Git Practices
Reads more naturally.
* rephrase hint block regarding remote name
* rework the resynchronization instructions per mtei
* use hint boxes for reference to Part 1 doc
I may be addicted to hint boxes. I'm sorry fauxpark. 😢
* add some clarity about the upstream repo
* wordsmithing per mtei
* restyle the shell code blocks
Makes them more consistent to the other docs in this section.
2.9 KiB
Resynchronizing an Out-of-Sync Git Branch
Suppose you have committed to your master branch, and now need to update your QMK repository. You could git pull QMK's master branch into your own, but GitHub will tell you that your commit is a number of commits ahead of qmk:master, which can create issues if you want to make a pull request to QMK.
?> This document builds upon the concepts detailed in Your Fork's Master: Update Often, Commit Never. If you are not familiar with that document, please read it first, then return here.
Backing Up the Changes on Your Own Master Branch (Optional)
No one wants to lose work if it can be helped. If you want to save the changes you've already made to your master branch, the simplest way to do so is to simply create a duplicate of your "dirty" master branch:
git branch old_master master
Now you have a branch named old_master that is a duplicate of your master branch.
Resynchronizing Your Branch
Now it's time to resynchronize your master branch. For this step, you'll want to have QMK's repository configured as a remote in Git. To check your configured remotes, run git remote -v, which should return something similar to:
QMKuser ~/qmk_firmware (master)
$ git remote -v
origin https://github.com/<your_username>/qmk_firmware.git (fetch)
origin https://github.com/<your_username>/qmk_firmware.git (push)
upstream https://github.com/qmk/qmk_firmware.git (fetch)
upstream https://github.com/qmk/qmk_firmware.git (push)
If you only see one fork referenced:
QMKuser ~/qmk_firmware (master)
$ git remote -v
origin https://github.com/qmk/qmk_firmware.git (fetch)
origin https://github.com/qmk/qmk_firmware.git (push)
add a new remote with:
git remote add upstream https://github.com/qmk/qmk_firmware.git
Then, redirect the origin remote to your own fork with:
git remote set-url origin https://github.com/<your_username>/qmk_firmware.git
Now that you have both remotes configured, you need to update the references for the upstream repository, which is QMK's, by running:
git fetch upstream
At this point, resynchronize your branch to QMK's by running:
git reset --hard upstream/master
These steps will update the repository on your computer, but your GitHub fork will still be out of sync. To resynchronize your fork on GitHub, you need to push to your fork, instructing Git to override any remote changes that are not reflected in your local repository. To do this, run:
git push --force-with-lease
!> DO NOT run git push --force-with-lease on a fork to which other users post commits. This will erase their commits.
Now your GitHub fork, your local files, and QMK's repository are all the same. From here you can make further needed changes (use a branch!) and post them as normal.