Tutorials

How To Ignore Unwanted Content in Git

September 24, 2018
Image of a code snippet on a screen

Let's explore how to create a special file that excludes unwanted content from Git repositories. After reading this description, you should be able to design and add a .gitignore file to your version controlled projects.

Gitignore is a special file that tells Git what files you want to automatically exclude from repositories. There are certain types of files that you don't want to commit because they're not actually part of your project, or because they are impractical to include in version control. Let me give you a few examples of what I mean by this. Version control helps you manage source code and assets. It's not meant to store compiled programs, or even intermediate compilation products like libraries or .o files. You can easily rebuild applications from your source code when needed. You don't want version control to waste space saving copies of already compiled materials, especially those that quickly go out of date. If you're never going to use them again, they're a poor fit for version control management.

Is source control meant to store your build logs or most data files? As a product of time, logs are not sufficiently interesting to justify multiple snapshots. As for assets, most data files won't change during development. Using version control to track memory intensive art, sounds, databases and other data files isn't a productive use of this tool.

Operating systems can leave a lot of junk, both visible and invisible, lying around your computer. These files are usually generated as a part of normal system operations. For example, you might find a Windows thumbnail cache, or a folder customization file that remembers icon positions or stores a background image. You want to omit these OS specific items as they have nothing to do with your project or the work you're trying to refine over time. Although I've only given you a few examples here, all of these files from compiled sources to logs, from data files to OS specific files, are all excellent candidates for inclusion in your .gitignore settings.

A .gitignore file normally lives at the top level of your repository, it specifies which files you want to automatically exclude from your commits. Alternatively, you can use Git to build a global .gitignore file in your home directory. This is what I'm gonna recommend you do. If you create this file properly, you can basically set it and forget it. You get all the advantages of .gitignore in every Git project you use. It's way easier than using separate .gitignore files for each and every project. You tell Git which file to use by issuing a global Git config command, and here it is. This starts with git config --global which configures Git globally across your personal computer account. It applies to any repo your account creates. The name of the option you're setting is core.excludesfile. And the path of the file you're setting this to is a .gitignore --globalfile in your home directory which is what that tilde at the start of this path means.

Now, let me clarify a few things for you. This command does not create this new file for you, it just configures Git to know where to look for the file, where that file is supposed to be. The file path, which here is in your home directory, and its name are conventional, and this is how most people set it up. If for some extraordinarily weird reason you need to name it something else, or you need to put it somewhere else, yes, you can do that, but don't do that. Convention exists for good reasons. When you follow conventions you always know where to look and what to look for. The location and its name are understood. These are best practices. If you stick this file somewhere else and you forget where you put it, you have to ask for help and you're generally up the creek. Yeah, yeah, you can use Git config to look at your settings to figure out where your .gitignore file went. But by then you'll probably have forgotten about which Git config option to look at and you'll just be in a mess. Best practices and conventions are there to help you They are not there to keep you from expressing your truest creative self.

Finally, you have to build the file and add content. Again, this is up to you. And until you do that Git is going to keep working the way it has always done even before you issue this command. It is the content that drives what .gitignore includes or excludes from each commit. So, go ahead and pop open a terminal window. Type the Git config command and be very careful. git config --global core.exludesfile ~/.gitignore_global Check for typos before you press return. There is a lot of text here on this line, so take the time to make sure it's correct. And remember you can always pause this video whenever you need to.

Next, create a new empty global .gitignore file and you do this using Unix's touch command. Again, pay special attention to the path and whether you've typed this correctly. Use LS, the list command in Unix, to confirm that the file exists exactly where you expect it to be and that it is spelled correctly. You're going to need to open and edit this file, but until you know what to put there, it's too early to worry about that. I'm gonna first show you a bit how .gitignore works, and then we'll come back and edit this file.

To start, I create a new folder on my desktop. I'm going to call it project. It is just a demonstration here. You do not have to follow along. I copy a HelloWorld file into that folder and then I run Git init which places this folder under version control. When I run git status it shows me I have an untracked HelloWorld file. So far so good.

Now, however, I'm going to open this folder using the Macintosh Finder system. I know you may not be on a Macintosh, but this is kind of to demonstrate how you can mess up your folder with operating system specific things. So, I'm going to mess with the icon size. This is guaranteed to generate a junk system file in my folder that talks about how I laid out my folder and its icons. Now, when I run git status, I see a new file, DS Store, and this file is created by macOS. I don't wanna use Version Control with this file, but git status sees it as just another file added to my folder. This is a perfect opportunity to use .gitignore. So, I opened my global .gitignore file and I edit it using content from a site called gitignore.io. Now, after I do that edit, when I say git status, the ugly OS specific DS Store file is gone from my untracked files list. It has not disappeared from my folder. You can see that because I did an ls, I listed the files and there it is. I have a little blue arrow pointing to it, but it's just ignored by Git and that's the whole point of .gitignore. It lets me exclude those files that I should not commit.

Gitignore.io lets you build .gitignore files, and it lets you do this using all kinds of keywords, you just paste them together into a conglomerated file. And it's really handy because it allows you to combine ignore sets from all kinds of use cases with a single button clip. You just copy and paste the results. And it doesn't matter what system you're running on, it works for Windows, and Linux, as well as Mac. Make sure to add as many keywords as you can for your operating system, for your editor, and for your programming language. And the IDE that you're using. If you can think about a keyword that describes your programming environment, try to see if there is a matching tag in .gitignore.

Remember this is a global configuration file, so if you're going to use Swift in one project and Python in another, add tags for both. And don't worry if you forget anything, you could always paste extra ignores in later. What you're creating is a simple basic text file. It lists individual file names like here, local.properties. It lists directories like ProGuard, the slash at the end tells Git to ignore all the files within the directory as well. It uses wildcards with asterisks. So, it can match all files with a class extension letting you ignore Java class files with a single entry. All the entries are grouped together for easier reading and maintenance. They're labeled with a pound at the start of each comment line. And when Git sees this pound sign at the start of a line, it treats it as a comment and it won't process any of these things I pointed to plus a whole bunch more that I ran out of arrows.

There's a lot more to .gitignore specification. Pasting my auto generated .gitignore content into my global .gitignore file and saving is what allowed Git to filter out all the files I didn't want to include. So now, it's time for you to do the same. Visit gitignore.io and create your .gitignorecontent. It doesn't have to be perfect the first time you do this. Don't worry, you can always redo this or add more later. Try to use as many keywords as you can that match the kind of work you do. But again, you can always add or update this later. Open the .gitignore file you created in your home file in your home folder, in your favorite editor. It doesn't matter which editor you use. Then just copy the content from gitignore.io and paste it into that file and save it. You are all set and ready to get to work.

Even though I like gitignore.io better, GitHub also hosts a decent repository of sample .gitignorefiles. Just hop over to github.com/github/gitignore and right now they have several dozen specialty files covering languages, applications, editors and more. You can select any of these pre built, .gitignore files where you set up a new repository on GitHub. GitHub automatically adds to your repo along with a readme file, if you check that box, and a licensed file, if you select one from the pull down to the right of the .gitignore selection. It's an easy way to set up your repository with convenient presets.

There are all kinds of files you simply won't want to track under version control. A well-built .gitignore file handles all these cases and more. As a rule it's not worth your time or bother to build your .gitignore files by hand. At best, you might paste together bits from various sources, if one site doesn't fully create the entire suite of ignore settings that you need. A .gitignore file is an essential tool for professional Version Control work. You may not need one now, as a student at Bloom Institute of Technology (formerly known as Lambda School), but it's a feature you'll want to know about and practice with before you enter the job market. And even at BloomTech, it will keep a lot of stuff out of your committed projects that you simply don't want to have there. Gitignore, it's a great and important tool.