When viewing a particular branch on GitHub, you will normally see a banner underneath the branch name stating ‘X commits ahead, Y commits behind main.’, which you may be wondering about and how this affects the synchronization of your key branches. See the example below for my ‘Hotfix’ branch.
This particular concept is more prominent on GitHub compared to some of the other Version Control Systems (VCS’) as you look at branches and consider raising Pull Requests (PRs) to other branches further along your release flow.
Note: When doing a Compare & Deploy in Gearset, we're only comparing any file differences for you, whereas GitHub really cares about commits, and thus may show extra items than you're expecting if the source and target sandboxes are actually in sync metadata-wise.
What does this mean?
The basic meaning behind these terms are as follows:
Commits ahead: The branch has X commits that are not present on your main branch:
This is usually due to layering on extra commits when developing new features, or due to Merge Commits being created when completing a PR from feature branches (which we’ll discuss later).
We can see my Hotfix branch is showing at 64 commits ahead, and by clicking on that link we can see the commits in question.
Commits behind: The branch has Y commits that are present on the main branch but not present on this branch:
This is usually a synchronization issue where the git histories are not completely aligned, which could be due to other features/hotfixes/commits being regularly deployed to main but not synchronized here, or simply the merge commits not being present rather than the features themselves.
If you’re using Gearset Pipelines, we have a document here going into more detail.
Again, clicking on the link for ‘behind’ shows me the commits in question that are present in main but not on my branch.
Why does this happen?
The main reason for why these differences will show up are due to the default behavior GitHub uses with using Merge Commits (explained here), and how well synchronized your branches are. We have a detailed technical explanation here also.
If you're using the Pipelines Branching Model, or it's underlying Expanded Branching Strategy without Pipelines, this will become more common due to the way feature branches are individually PR'd against your environment branches and merged, meaning new unique merge commits are added onto each environment branch as the feature progresses.
Merge Commits
These are special commits layered onto a target branch when a PR completes, essentially tying the 2 separate histories together (Source Branch and Target Branch) and showcasing the source commits were merged into the target at this point. This article from Atlassian explains it also.
As referenced above, if you're using an Environment-based branching strategy where feature branches are individually merged to each environment target branch, this will generate these unique Merge Commits for each merge, which will never be synced up to main (as you never directly merge an environment branch forwards, only the individual features), meaning the 'ahead' number will keep increasing.
Synchronization
As more and more feature commits are layered onto your main branch through genuine development/hotfixing, the main branch will get further ahead of your environment branches, and that's when the 'X commits behind' will show on those.
If you only have 1 direct stream of development through set branches and sandboxes, it's very likely the commits present on main are simply extra Merge Commits from the final PRs, and opening a Sync PR in Pipelines, or a direct PR from main > environment branch in GitHub, can synchronize those histories up for you.
When viewing the commits in GitHub, you should be able to tell the Merge Commits by looking out for messages starting 'Merge pull request #XXX from', rather than your usual commit messages for real features, as shown below.
If you do have multiple streams of work heading into Production, such as a dedicated hotfix route or faster-moving feature development work, you may see genuine feature commits present that could be brought back during the sync, so assessing whether that's the right time to do that synchronization will be key.
Summary
As a summary; when using the default Merge Method in GitHub, unique Merge Commits will be layered onto your target branch as you merge feature branches through, which will cause those branches to show commits ahead/behind your main branch.
Regularly syncing up those environment branches from master will help prevent unexpected commits showing up in your PRs and the branch showing as 'behind' in GitHub directly.