Page contents

Git Best Practices - Gitential's Top Ten

Share on facebook
Share on twitter
Share on linkedin

Run-through

How to be a great Software Engineering Manager?

How to be a great software engineering manager?

Being a great software engineering manager is a continuous balancing act. Balancing between the interest of team members, the team, the company and clients, as well as your own. It requires both technical and social skills.

I this article we broke down engineering managers’ tasks into bite-sized chunks. Read further and let’s improve together.

Read More »

By GITENTIAL TEAM

Git is one of the most commonly used distributed version-control system, designed for coordinating work among programmers. Its main purpose is to track changes in source code during software development, but you can use it to track changes in any set of files. With Git, you can improve speed, data integrity, and support for distributed, non-linear workflows. It is suitable for any size of software project, large and small.

You shouldn’t be too disappointed if you were expecting us to definite Git as an “unpleasant person” in English parlance. Git was created by Linus Torvaltz, the same developer who created Linux. Drawing from the Git FAQ, Linus is quoted as saying, “I’m an egotistical bastard, and I name all my projects after myself. First ‘Linux’, now ‘Git’.” While we don’t know Linus personally, we do think he’s a genius, and we like him whether or not he’s seen fit to take sensitivity training.

But let’s go back to our topic. There are many reasons why software developers and engineers love Git – it’s fast, easy to learn, and it’s free. As a result, it is very, very popular. Help your team get the most out of this awesome tool.

Version control makes it possible to track and manage changes (a commit or revision) to a document or to software source code over time. While it is helpful to identify the latest version of a file, that doesn’t mean it is the “best file” – it can have errors. File versions let developers revert back to a point when or before the error was introduced. The developer can then correct the mistake to reduce the impact it has on the efforts of other developers.

Every time a “commit” is made Git assigns the file a unique ID. The process creates a record of changes made, who made them and when.

For the layperson unfamiliar with Version Control Systems like Git, a repository is a data structure for all of the folders and files associated with a project. Git’s data structure also reflects each file’s history – the revisions made to it via “commits.” Git provides distributed repositories that maintain a copy of this information on every user’s system.

A commit is essentially a saved file capturing a snapshot of its development. Each commit can have branches that reflect different versions of a file version. A branch would be created, for example when John finishes his work on a file and hands it off to Mary to develop further. If Mary discovers a bug in John’s version of the file, he’ll need to fix it. The new file will have a new file version. Mary’s work on the new file version starts a new branch.

As some projects may involve a dozen or more developers, a good VCS is essential. The organization and file protection Git provides enables developers to work on new features, fix bugs and bad code without impacting everyone else’s work.

Our 10 Git Best Practices

Tip 10. Bookmark the Git manual and other useful resources.

Maybe you’ve never used Git before or you’re working with team members who are new to it. Maybe you’re using it and the going is getting tough. Checkout and bookmark the following Git Resources so you always have them at the ready: If you would like to nominate another Git resource to this list, please drop us a note at twitter.com/gitential

Tip 9. Define and divide work into separate repositories.

For practical purposes, you can have as many repositories as you need to make your project and portions of it easier for everyone.  Everything that is in a Git repository is available to everyone that has access to it. Consider, that most of the projects involve NDA’s, security clearances, contractors and other third parties. Compartmentalizing is a good idea.

For starters, you’ll want to Get a Git Repository. You’ll need to define whether you want to maintain one super-repository or separate ones for all of your ongoing projects. Think about how your teams are organized and to whom tasks are assigned. Think about the project and its different components and features, or the libraries and classes it will use.  Defining the repository structure in advance can save a lot of headaches and rework later.  Git-modules and Gitslave can help you manage your repository structure. Think about having repositories for the following cases:
  • A company or team-wide super-repository for all projects.
  • Repositories for files shared by multiple projects for easy re-use of code. Individual repositories for each project.
  • Repositories for logical teams (internal, contractor, third-party), OR
  • Repositories for logical segments of a project – per library or class, product or feature, etc.
  • Repositories for large binary files – not handled particularly well or fast by Git.
  • Any others you think you’ll need.

Tip 8. Create and Use a Step-by-Step Checklist

Checklists for a reason

Checklists are not a new invention. Think about the air crews who are following step-by-step checklists to prevent crash. Or a good UI/UX designer using a checklist to avoid forgetting any of the important things.
Amazon keeps a detailed SOP on every job function in their distribution centers. Every branch of the military does exactly the same. this applies to why companies seek, practice and maintain compliance to any number of International Standards Organization (ISO) programs.

Why the detail? Several reasons, starting with maintaining a consistent standard – that if followed will always lead to a desired outcome or at least not break something. The checklist is a map to take you to your destination. If you arrive “someplace else” you can retrace your steps to find out where you took a wrong turn. Another advantage is that you can provide the checklist to a new team member and have confidence they can follow it. It is, if nothing else, a training tool.

Checklist for Git

Git is complex, as can be expected of anything that involves tracking continuous changes to a project by multiple developers and engineers. Writing a checklist or SOP for your team may take a few hours, and some refinement over time. Neal Humphrey created a practical Git Checklist for new team members to help get you started. Most mistakes made in Git can be fixed quite fast while others can be more cumbersome. It’s usually not the fix, but finding the fix, that can consume a lot of time for new Git users.

Having a library of Git resources, defining a structure, and defining the work process let’s us get into more granular Git best practices.

Tip 7. Test first, commit second.

Test your changes before committing them to a repository available to other team members. Trust but verify is a good policy even when you’re the only developer on a project. Even if you are confident that your changes will work, testing changes first will increase other’s confidence in your work. The cost to test your changes will always be less than the cost of introducing a bug or problem that impacts everyone.

Tip 6. Commit early and often.

Smaller and more frequent changes enable others to integrate your changes more efficiently than large changes. Smaller changes make it easier to write clear commit messages. Larger changes introduce a greater chance of missing details in the writing or the reading of the commit message. More frequent commits provide you more waypoints to revert to if you break something. This reduces the amount of work and code you lose with each error. See: git-reflog.

Tip 5. Write good, clear commit messages

Make sure everyone understands the reason for your change. Start with a Header of ~50 characters describing the change. In the body of the message, define the reason for the change and how it is different from previous versions. Use command words in the present tense for consistency with Git messages. Aim to be as clear and concise as possible. Everyone will benefit from being able to easily determine if they are reverting to the right file.

Tip 4. Stash, don’t commit, unfinished work

When working on a large section of code, it’s considered best practice to break it into smaller, closely related or logical segments. Nevertheless, there’ll be occasions where you’ll want to save your work – even if it isn’t finished yet. Instead of committing your work, use git-stash. This command will keep a record of the current state of your working directly. You can then go back to a clean working directory or whatever else you need to do – and pick up where you left off with git-stash apply.

Tip 3. Structure and branch workflows to fit the project

Workflows cannot be immutable, but must be adapted for the peculiarities of each project. Developing software for existing hardware devices is very different from designing companion software for Internet of Things devices that may still be under development. The likelihood for change in the underlying architecture, technologies, and requirements of these two types of projects are poles apart. While we’re discussing structure and branching, sometimes it’s not necessary to reinvent the wheel. Seth Robertson discusses branching workflows in considerable depth in his own list of “Git Best Practices.” Seth also provides a list of additional references which we would like to share here, too:

Tip 2. Enforce standards

Enforcing standards with Git applies on two levels – automating “forced compliance” to standards and active management of team compliance. Automation makes it easier for everyone to consistently meet the standard while avoiding many frequent mistakes. Within Git, hooks are used to customize a Git-enforced policy to check for “a custom commit message format, and allows only certain users to modify certain subdirectories in a project.” On Medium, Shamique provides some nice examples of how to use Git hooks to prevent console logs and validate commit messages. If you find his examples useful, then you’ll be able to unlock a veritable treasure trove of Git hooks on, remarkably enough, githooks.com. Going back to Avoiding Technical Debt, several points apply to how you work with and manage your personal and team’s work processes in Git. The most direct of these is to, “Communicate, maintain, and enforce consistent quality standards so all team members and outsourcing providers know what is expected of them.” Enforcement lends itself to at least five of the other best practices for avoiding technical debt:
1. Use automated Git and software development analytics tools to track performance metrics.
2. Self-document your codes, avoid ambiguous variables, names and statements.
3. Conduct frequent (daily) software code reviews, the advantages are numerous.
4. Keep components modular and avoid coupling components together extends equally to best practices for commits.
5. Take extra steps to ensure new hires and junior software developers are mentored in best coding practices - make sure they have the Git resources and a checklist that’s customized for your team.

Tip 1. Stay calm.

Remember Murphy’s Law, Sod’s Law, and Finagle’s Law, “Anything that can go wrong will go wrong, at the worst possible time, and in the worst possible way.” Usually, it doesn’t. When it does, just use your imagination about how much worse it could possibly get.

  • First, the comic relief is good.
  • Second, your situation is probably not as bad as you think. Third, in all cases, panic is your worst option.

You can’t prevent all bad scenarios all of the time, but with a little forethought, you can prevent almost all of them, most of the time. Following our Git Best Practices will help you do just that. Mistakes, accidents, and events beyond your control will still happen. But, just about everything you commit on Git can be restored if accidentally deleted. If you do make a mistake, don’t try to hide it – rather inform other team members so they can delete or re-pull the branch in question.

The more you and your team apply to frequent, single-purpose, well-documented requests, the less work and searching you’ll have to do if you need to revert back to an earlier version.

Bonus tip - sign-up for a free trial on Gitential!

Gitential is like “Google Analytics” for software development. Our automated analytics helps software engineers and software project managers track developer performance to measure efficiency, identify, and correct trends contributing to technical debt. If you have any questions about how Git analytics can help you, please let us know at gitential@gitential.com. We welcome you to sign up for a free trial, no credit card is needed.
How to be a great Software Engineering Manager?

How to be a great software engineering manager?

Being a great software engineering manager is a continuous balancing act. Balancing between the interest of team members, the team, the company and clients, as well as your own. It requires both technical and social skills.

I this article we broke down engineering managers’ tasks into bite-sized chunks. Read further and let’s improve together.

Read More »

Spread the word

Share on facebook
Share on twitter
Share on linkedin