Version Control Best Practices for Bootcampers: Understanding Git Branches and Avoiding Divergence

Intro

As a cloud developer, mastering version control is essential. Git is the most popular version control system, and it's widely used in the industry. However, many beginners face challenges when using Git, especially when working on the main branch only. In this article, we'll explore some of the common pitfalls that bootcampers encounter and how to avoid them.

Problem Statement

When working on the project's application, organizers recommended using the main branch in the repository to avoid branching complexity for beginners and minimise the risk of forgetting to merge their changes into the main branch before homework submission.

The repository typically contains the application code and a student journal for homework assignments. Students often use GitHub to edit their journals as it has a preview feature, and the GUI for committing changes is user-friendly. In contrast, students use GitPod to work on the project application and commit code changes to the same Git repository.

However, working on the same branch from different code spaces can create problems, particularly when journaling on GitHub and coding on GitPod. Students may see errors that require them to merge the code before pulling and pushing their code. This can be frustrating for beginners who are not familiar with Git terminal commands.

What is going on under the hood?

To understand the issue, we need to look at the three trees of Git: working directory, staging index, and commit history.

These concepts are well explained in this article: Reset Demystified.

We also need to understand what remote origin is.

In this case, GitHub serves as the remote origin, while GitPod clones this repository as a local copy each time a student spins up an environment or keeps working on it. The GitHub repository is the parent (remote origin), and the GitPod local copy of the repository is the child.

When a student changes their journal on GitHub after spinning up a GitPod instance, it creates a divergence in the main branch of the repository. The GitPod instance was sleeping and not fetching updates from the remote origin where the journal is hosted.

When the student resumes work on the code changes on GitPod and tries to push them to the repository, Git returns an error since the branch is diverted, and the local copy doesn't have all the commits in the history.

Visually the problem looks like this:

Best Practices to Avoid Divergence

Here are some best practices to avoid Git divergence issues:

1. Make small frequent changes with atomic commits - this saves time on troubleshooting and reverting problematic code. It's easier to find the commit with the code change that brought trouble when traversing the git log.

2. Do fetch before push if working on the same branch in different code spaces such as GitHub for journaling and GitPod for the code changes.

3. Alternatively, work on the journal in a separate branch but don't forget to merge it into the main before submitting the week's work.

4. prefer to merge to rebase because merging is non-destructive action. here is excellent article from Atlassian: merge vs rebase

5. Preferably use Git commands in the terminal rather than VSCode GUI in GitPod. It helps to understand Git better, especially git status, untracked/staged changes, and Git feedback on git push command in case the local main branch diverted from the remote origin in GitHub.

Conclusion

Version control is essential for every developer, and Git is an excellent tool for managing projects. However, using the main branch only can create divergence issues when working on different code spaces such as GitHub and GitPod. By following these best practices, you can avoid Git divergence and make your development experience smoother.