This is a collection of tips that I have found useful for introducing software developers to the Git version control system.
Bookmarks for reference
- The “feature branch” workflow as documented by Atlassian.
- Flight manual.
- Git simulator.
For users
When you say that you use Git, most developers will assume that you are familiar with the Git CLI. Regardless of whether you plan to use the CLI long-term, when you do a web search to find out something about Git, you should be prepared to read answers that apply to the Git CLI.
Since you will be asking a lot of questions in the first few weeks, you will have less work to do if you use the same interface as everybody else. Rest assured that there are plenty of graphical tools and IDE plugins that you can try out later.
Takeaway: Use the Git CLI while you are learning
If you have more than one person working with the code, then you will want to share your repository between them.
You need product that meets your budget, workflow, security and licensing needs: As of 2018, you really only need to consider GitHub, Bitbucket, Phabricator or GitLab to make a thorough comparison.
Takeaway: Demand a collaborative environment that supports ‘pull requests’
Repository admins
Aim to make your setup both beginner-friendly, and beginner-proof.
Git is not very opinionated, and has features which will support many advanced workflows. I would suggest that you save these features until you have a critical mass of experienced users who are comfortable using them. The feature-branch workflow is beginner-friendly, as long as the shared branch is never changed.
Ensure that your whole team has mastered the basics before you try to get creative.
Takeaway: Just use the feature branch workflow initially
There are a few switches that you should set in your system to prevent mistakes from disrupting users who do the right thing:
- disable forced-push on the
masterbranch - require a pull request and one approval to modify the
masterbranch
The name of these settings will depend on the software you are hosting on, but for example, on GitHub, this is known as a “protected branch”:
These settings prevent people from re-writing history on the main branch, which is bad Git etiquette. Usually people are trying to re-write history with good intentions, such as trying to scrub credentials, huge files, or other extras that were accidentally included.
Good software process aside, a lightweight code review process will make accidental changes more visible, so that you can give developers a chance to fix their mistakes without propagating them to other developers.
Takeaway: Don’t allow direct access to master
Git champions
There are a few setup steps that users may not discover on their own, which avoid common frustrations.
A classic newbie complaint about Git is that it makes you enter passwords “all the time”. This is not really true, but to give users less things to complain about, ensure that they do the initial clones over SSH.
This involves generating a key and uploading it to your hosting software. Subsequently, you will never be prompted for credentials.
Takeaway: Show users how to clone with SSH
Immediately after you make your first commit, Git will point out that the author name has not been set, suggesting that you should amend the commit. I think that the experience is far better when this is configured pro-actively:
git config --global user.name "Example Bob"
git config --global user.email "bob@example.com"
The first time that this user finds a merge conflict, they will appreciate having a graphical, point-and-click merge like meld.
Follow OS-specific instructions, then run:
git config --global difftool meld
Takeaway: Step new users through the author and difftool settings.
Conclusion
The dominance of Git as a software revision control tool means that it’s worth investing some time to learn it properly.
If you get one thing out of this post, though, it’s that you shouldn’t attempt to be creative about your use of Git until you know what you are doing.
I’ve tried to avoid mentioning intermediate or advanced features in this post. As you become more comfortable with the basics, you can use the flight rules and simulator at the top of the post to discover some of the things git can do, and the situations where you might want to use each feature.