If you have a team of software engineers and want to move them to Mac, you will need to consider a number of things before you do so.
Git Best Practices - Gitential's Top Ten
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:
- Get The Git Manual
- GitHub guides for Git.
- Get GitHub’s Command Cheat Sheet for Git
- The Git Wiki
- Get some Git GUI’s.
- Git on Reddit.
- Join the Git Community Mailing Lists.
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:
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.
Moreover, you always have an ability to look for help from specialists in some concrete field. Thus, for example, you can hire email marketing specialist to set up better connections with your team. Briefly, email marketing means a process of adaptation communication with people through emails. It can be especially helpful when working with a team distantly. It is a fact that some unpleasant situations will appear and the first thing you should do in such situations is tell your colleagues about the problem. Firstly, to warn them about possible difficulties. Secondly, to look for a solution together as it is the most effective method.
And an email marketing specialist can help you to build a strategy of clear and pleasant communication for all sides. It can bring you some relief in work and save a lot of nerve cells for both you and your colleagues. As people mostly have low resistance to uncertainty it is important to keep in touch with those that depend on you for them to be aware of what is going on. It can decrease possible distress a lot and keep your way of work continuous. And, of course, as a result it will lead to better results of the work and rising productivity as all participants of the process will understand the situation and make some steps for solving possible problems.
So just keep in mind these tips to achieve your best working with Git. And remember all of the time last but not least tip “To stay calm”. Just install good communication with all team members and keep in touch all of the time. This rule is a 99,9% solution to all problems, especially at work. And remember, less stress leads to more results!
Post updated: February 6, 2023
If you have a team of software engineers and want to move them to Mac, you will need to consider a number of things before you do so.