When pulling or pushing your branch there are 4 states you may find yourself in:
-
Behind Github - Github has all the commits on your working copy of the branch, plus some extras. When you are updating your copy of
main, it will always be this state. A feature branch may be in this state if you've been pairing -
Ahead of Github - your branch has all the commits that Github has, plus some extras. Your feature branch will be in this state most of the time
-
Diverged from Github - you have added additional commits to your branch and somebody (or something) has pushed commits to Github in the meantime. eg. Github could have update the visual test snapshots
-
Diverged from Github with gaps - you have removed some commits that Github used to have, or someone has removed some commits from Github that you used to have.
git rebasehas been recently used to squash, reword or delete some commits
These 4 states can occur at multiple points during your use of git and over time you'll get a good sense for which state you are in. However, it's possible to work out which state you are in using a few simple steps:
> git fetch
This is 100% safe. All it does it pull the latest changes from Github - it doesn't attempt to integrate them with your local branch. It's important you don't miss this step, otherwise you may not have the most up to date copy of your branch from Github.
Tip: You can configure git to do this in the background for you.
> git status
If you are Behind Github you will see:
Your branch is behind 'origin/rs/git-playground' by 1 commit, and can be fast-forwarded.
If you are in Ahead of Github you will see:
Your branch is ahead of 'origin/twr-2317' by 1 commit.
If you are in Diverged from Github or Diverged from Github with gaps you will see:
Your branch and 'origin/rs/twr-2471' have diverged, and have 2 and 1 different commits each, respectively.
It's less common to be Diverged from Github with gaps, but when you are, you need to be careful. See section below on how to work this out.
Let's put this knowledge to work by looking at 3 common tasks.
Perform a Fast Forward Merge
> git merge --ff-only
This is 100% safe. It's only possible to complete this if you are Behind Github:
- ✅ Your branch is behind Github
- ❌ Your branch is ahead of Github
- ❌ Your branch and Github have diverged
- ❌ Your branch and Github have diverged
If it fails, you may have accidently commited to main:
> git merge --ff-only
fatal: Not possible to fast-forward, aborting.
You may find you're trying to do this in the following states:
- ✅ Your branch is behind Github
- ❌ Your branch is ahead of Github There's nothing to do.
- ✅ Your branch and Github have diverged
- ✅ Your branch and Github have diverged with gaps
If Behind Github - Perform a Fast Forward Merge
Note: you will never have any conflicts to deal with during a fast-forward merge.
If Diverged from Github
First, you'll need to work out if your branch has just Diverged or Diverged after a force push.
If you are working on your own, it's likely you are just Diverged. You most likely ran the Update Visual Tests and then carried on committing in the meantime.
If you are pairing, and your partner has not force pushed, it's likely you are just Diverged. They've pushed some new commits to Github while you carried on commiting in the meantime.
If your partner has previously force pushed, it's likely you are Diverged after a force push.
If it's not obvious use can use git log to work out the situation:
git log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset%n' --abbrev-commit --date=relative origin/{BRANCH_NAME} {BRANCH_NAME}
PS: this command can be shortened 😅
If you're just Diverged the graph will look a bit like this:
* da423dd9 - (HEAD -> rs/git-playground) chore: bump node version (2 minutes ago)
| * f079071c - (origin/rs/git-playground) feat: allow user to delete cookies (7 minutes ago)
| * 231af086 - fix: deletion message not appearing (2 hours ago)
|/
* 931b42d8 - feat: allow favourites to be removed (2 hours ago)
* a7ffa49b - (origin/main, origin/HEAD, main) [TWR-2501] Add copyright message to bottom of local link maps (#874) (6 hours ago)
* 5e76a93f - [TWR-2339] 2️⃣ Extract utils in prep for use in other clients (#870) (10 hours ago)
* 8eb8eb0a - [TWR-2489] Fix padding/gap issue in Markdown (applies to local link slug page) (#872) (26 hours ago)
* d60ccffb - TWR-2485: implemented forced GMT time on first and last tram time stamps (#871) (27 hours ago)
* 49a6e296 - [TWR-2339] 1️⃣ Log backend api errors to cloudwatch log insights (#867) (32 hours ago)
If you're Diverged after a force push then some commits will be missing:
* 0914885c - (HEAD -> rs/twr-2471) fix import issue (31 minutes ago) <Rob Squires>
|
* c850c95e - wip: all bus route typeahead to be used with old GQL api (13 hours ago) <Rob Squires>
|
| * ab61ca13 - (origin/rs/twr-2471) wip: all bus route typeahead to be used with old GQL api (14 hours ago) <Rob Squires>
|/
|
* 0cf4264a - [TWR-2480] Add Space in center of Postcode when displayed (#865) (2 days ago) <Alex Austin-Puhr>
|
* 5da55e02 - Equals lint rule (rule for === > ==) (#864) (2 days ago) <Alex Austin-Puhr>
|
* 7d4325cb - [TWR-2465] allow Local link to return multiple results (#863) (3 days ago) <Alex Austin-Puhr>
If you are not 100% Certain you a just Diverged, the best thing to do is ensure you or the person you are pairing with has a backup copy of Github.
Then you can integrate with Github using:
> git rebase
This is not 100% safe, but if you get conflicts rebase is able to guide you through resolving them.