git repository best practices

Details
Category: Tips
Published: Thursday, 30 July 2020 23:09
Written by Christopher Carr
Hits: 1653

git is today’s source repository manager of choice for software development professionals, but increasingly it is being misused or abused. Here are some hints to make your git usage more professional and hopefully some reasons as to why.

git is efficient at managing changes in text files, but not so for binaries.

.gitignore

What is it?

The .gitignore file (note the . in the filename) is a reserved file used by git that identifies project files & folders which should not be written into your repository and therefore identifies the remaining subset of files that are necessary to your project.

Files that should not be included in your repository are binary outputs and other generated files from your build process. The .gitignore file should also exclude any other files that do not constitute “source”, for example files containing secrets used in local development.

There are many web resources where you can learn all about the structure of the .gitignore file.

Why use a .gitignore file?

While you can stage selected source files in each commit, who wants the hassle of manually selecting relevant files for each commit? It is both time-consuming and error prone.

If you don’t have a .gitignore file in your repository, you increase the chance that you will include files in your commits that you don’t need (or want) in your git repository.

It should be noted that manually selecting files to stage increases the chance that you will miss something that should be checked in.

Exclude binaries

Binaries in your repository, especially binaries that change, lead to repository bloat because git stores each change to a binary as a complete copy. This is a bad thing since the larger the git repo, the longer it takes for someone to pull it down and start working on it.

NuGet packages are a special type of resource used in dotnet projects. They should never be stored in your repository as they are binary and often quite large. NuGet packages do not change once published, so you can use the command dotnet restore to retrieve the packages for your dotnet project.

Where can I get a .gitignore file?

If you’re using dotnet, you can type dotnet new gitignore to create a dotnet specific .gitignore file in the current folder.

For other project types, GitHub maintains a handy collection of .gitignore templates

https://github.com/github/gitignore

More than one .gitignore file

While it is normal to include a single .gitignore in the root of your repository, you can have as many .gitignore files in your repository as you have folders.

If your repo contains more than one type of project, it is common to have a .gitignore file in the root of each project folder.

readme.md

When you create a new repository, it is good practice to add a readme file in the root of the repository explaining what the repo contains, where it is used and how it is built & deployed. This file acts as the starting point for any new development or collaboration or as a quick-
start on a project that may not have been touched for some time.

A standard git readme uses markdown format (hence the md extension). Markdown supports simple formatting like headings, bullets and lists.

The readme file is an essential part of your application source code, and it should be maintained alongside code changes. In fact, many organisations have a question on Pull Request creation asking you to confirm that you have updated the readme file for this very reason.

You should add a readme.md in the root of each git repository. Of course, if you have several projects in your repository, you can have one readme.md per project in each project folder.

Your readme file should contain the following minimum detail

  • Project title: A one or two paragraph statement explaining what the repo is about
  • Build Status in Continuous Integration (CI)
  • Installation instructions and/or usage example(s)
  • Development setup – required tools, frameworks and how to build the project
  • Test setup – how to run the tests with examples
  • Release History – with changes and bug fixes. Especially good for public repos
  • Credits
  • License

There are several sample readme templates on GitHub that are easily found via google.