How to Use the .gitignore File

For any software developer or programmer working on a development project, using Git for version control is nearly a requirement. And, if you use Git, the chances are pretty good that you are familiar and perhaps even proficient with GitHub. Many software development projects and applications live on GitHub as it is a powerful collaboration tool built around the underlying version control process. GitHub is not the only game in town, but it is perhaps the most popular and widely used globally.

The basic workflow around GitHub involves creating a branch of an existing repository into your repository, making whatever changes to the repository, creating a pull request, and when approved, merging the pull request and then deleting your branch. This process is high-level but captures the basics of working within GitHub. However, within the finer details of adding your changes back into a repository, not every file you created needs inclusion in the primary repository.

Deciding which files to include and which to ignore is where the .gitignore file comes in. This post will explore .gitignore, how to use it, and cover some use cases.

What is a .gitignore?

Software development projects come in all shapes and sizes on GitHub. GitHub works as a version control platform for a project that needs it, such as writing or research. However, GitHub is probably best known for version control of software development projects. As the project grows and changes, files are modified, added, or deleted. No matter the changes, sometimes there are additional files that don't need to be included in the final product or throughout the different versions and revisions.

Determining which files to exclude is where the .gitignore file comes in. Using .gitignore is as straightforward as it seems, but we can do more digging to understand better how it works. While using Git for version control, the program monitors all the files created and modified. The program handles all the changes in three ways: Tracked, Untracked, and Ignored.

Tracked and untracked have to do with whether the changes are staged and committed or not staged and committed yet. Committing the changes is the same thing as saving the work. The power of Git and GitHub is the ability to revert changes if the testing or implementation didn't work as intended. As this process of iteration and testing happens safely in the isolated branch of the user, there's no risk to the main branch of the overall project.

Whether making commits within the isolated branch or sending the changes up for review, there are almost always some files you can safely exclude. This decision to include or not include files is the primary function of the .gitignore file. In the simplest of terms, using .gitignore tells Git which files to ignore when committing changes to a project.

How to Use .gitignore

The .gitignore file is part of the root directory for a given repository and as such, accessing and using .gitignore happens within the command-line interface. .gitignore is a plain text file where each line added includes the ignore instructions for Git to execute. Both files and directories are typical examples of ignored files. It is important to note that .gitignore doesn't inherently come with a repository. Including a .gitignore file is as simple as creating that file either locally or globally in the root directory of a project.

There are a few commonly used wildcards and commands with .gitignore files.

• Adding in a .FILENAME tells Git to ignore that specific file.

• Using * tells Git to match and ignore all matches. For example, if there is a specific file extension that a developer needs Git to ignore, using the command *.txt will ignore all files that end with .txt.

• Another option is to ignore entire directories. Perhaps there were placeholder images used solely for testing. Using the images/ command, for example, will tell Git to ignore the images directory.

• Much like within a code editor, using the # allows for comments.

• Another common command is a bracket. Using [...] tells Git to ignore files or a range of files within the brackets.

• Developers can configure a .gitignore file for an entire system. This file is a global .gitignore. There are stark differences between operating systems and the respective command line prompts. However, .gitignore_global achieves this result.

• A developer can see the files that they told Git to ignore with the command git status -ignored. This command is valuable for projects with many ignored files to ensure a needed file doesn't get accidentally ignored. 

These commands and wildcards are the basics of .gitignore, and they can be used in patterns or more involved methods, depending on the complexity of the software project. For those that want to go deeper with .gitignore, an entire repository exists, complete with templates.

Use Cases for .gitignore

There are several reasons why a developer wants to ignore specific items using the .gitignore file. Generally speaking, not all files created or used during development, upgrades, or testing are appropriate for inclusion in the principal repository. Blank files or placeholder data used only for testing are great examples of the types of files to tell Git to ignore.

While working within a repository, many files are created in a temporary nature to support updates or upgrades. A fair number of those files are better left out of the main repository when committing the changes. A few examples include sensitive or privileged data, such as API keys or login passwords.

Other types of files that probably do not need inclusion back into the main repository are local system files. System-specific files would clutter the original repository and provide no additional value. A few examples of unnecessary system files include:

• Mac OS: .DS_Store; .AppleDouble; .LSOverride

• Windows: Thumbs.db; Thumbs.db:encryptable; ehthumbs.db; *.stackdump; *.cab; *.msi

• Linux: .fuse_hidden*; .directory; .Trash-*; .nfs*

Depending on the level and complexity of the development work, program dependency files included by package managers are often very large and unneeded. These types of files are downloadable to a local system and would create too much bloat and unnecessary files within a repository.

A great example is the text editor workspace files that are a part of popular tools such as VSCode, Sublime, or Brackets. Not every developer will use the same text editor, so including those files in the main repository would be unnecessary as the local system already has these files. NPM packages are another example. Those belong on the local system, not uploaded to a GitHub repository.

Getting More Out of .gitignore

Software developers, programmers, and even hobbyists that use Git and GitHub almost certainly understand the power and importance of the .gitignore file. Without .gitignore files, many repositories would have thousands of unnecessary files and directories that would cause many problems. 

Learning how to use Git, GitHub, and the .gitignore file are valuable skills that any level of software developer needs. Understanding the ins and outs of Git and GitHub is a skill and discipline not dissimilar to learning a new programming language. As you learn and become more familiar with Git and GitHub, utilizing the effectiveness of .gitignore will become second nature.

It's never too late to learn GitHub, and CBT Nuggets has the training material to help. Our course, Learn GitHub, is perfect for those just getting started, with plenty of instruction on using the .gitignore file. Our course is designed for all levels and is appropriate for seasoned engineers looking to brush up on their GitHub knowledge or junior developers interested in a jump start with GitHub.