In this post, we're going to look at how we can do some configuration to control and ensure certain types of files and directories are not included into our git repository. Often when creating Git based version control repositories, there will be certain types of files or even folders that you will want to exclude from being controlled and managed within your repository. These could be files that could be generated by your project at run time or output from various processes. Integrated Development Environments (IDE) and Operating Systems (OS) also generate hidden files and system generated file which should also be excluded from repositories.
Git makes this job really easy for you by enabling you to create what is known as a Git Ignore file.
What is the .gitignore file
.gitignore file is essentially a text-based file that developers can use to list specific files, file types and
folders to be excluded from being added or managed by a git repository.
Git is a popular version control system provides the ability to create a Global and Local and these have very specific purposes and developers should definitely making use of both these ignore file options on their development workstations.
What is a Global .gitignore file
All the popular OS (Linux, Mac OS and Windows) often create hidden files in directories that will often contain metadata and other information which you typically don't want to include in a git repository. These not only add clutter to your git repository, but they could potentially leak sensitive information. Developers should also exclude files and directories created by their favourite tools and frameworks that are not necessary to be included.
All these files and directories could be added to a local .gitignore file to be excluded, but this is not regarded as best practice. Due in part, that it becomes complicated and does clutter your project specific git ignore file with all the various OS specific and Tool specific file types.
Most developers will be creating and sharing hundreds of git repositories and having to remember copying these settings over project to project is less than ideal. Fortunately, git enables you to create a Global .gitignore file which is respected by git throughout your User Directory with rules that should be applied to every git repository.
This is usually achieved by creating a hidden file in your Home directory with rules that are specific to your system.
A global .gitignore file is best used for common files like
node_modules etc which you will
almost never want to commit to a git repository.
How to create a Global .gitignore File
We mentioned earlier that a
.gitignore is just really a simple text-based file and they are really simple to create.
In this example we'll create a Global
.gitignore using the terminal window , in our user home directory.
This will have created a blank hidden
.gitignore in our Home directory. We verify that it exists by :
ls - a $HOME
We can now populate this file with our environment specific data that we would like to exclude from any new or existing repositories we create and use on our machine. Github provide a very useful collection of useful Global .gitignore templates you can use to tailor your global file.
In my particular case, I predominantly use Jetbrains Based IDE's and Tools such as
PHPStorm, GoLand etc.
on Linux based computers. So typically use the defaults that are provided in Jetbrains Ignore and
the Linux Ignore
file settings. Occasionally I may do this by opening the new created
.gitinore in my preferred text editor and
pasting the values defined below in. However, I have mostly use my own automated process to create git ignore files
The values I typically include are:
# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839 # User-specific stuff .idea/**/workspace.xml .idea/**/tasks.xml .idea/**/usage.statistics.xml .idea/**/dictionaries .idea/**/shelf # Generated files .idea/**/contentModel.xml # Sensitive or high-churn files .idea/**/dataSources/ .idea/**/dataSources.ids .idea/**/dataSources.local.xml .idea/**/sqlDataSources.xml .idea/**/dynamic.xml .idea/**/uiDesigner.xml .idea/**/dbnavigator.xml # Gradle .idea/**/gradle.xml .idea/**/libraries # Gradle and Maven with auto-import # When using Gradle or Maven with auto-import, you should exclude module files, # since they will be recreated, and may cause churn. Uncomment if using # auto-import. # .idea/artifacts # .idea/compiler.xml # .idea/jarRepositories.xml # .idea/modules.xml # .idea/*.iml # .idea/modules # *.iml # *.ipr # CMake cmake-build-*/ # Mongo Explorer plugin .idea/**/mongoSettings.xml # File-based project format *.iws # IntelliJ out/ # mpeltonen/sbt-idea plugin .idea_modules/ # JIRA plugin atlassian-ide-plugin.xml # Cursive Clojure plugin .idea/replstate.xml # Crashlytics plugin (for Android Studio and IntelliJ) com_crashlytics_export_strings.xml crashlytics.properties crashlytics-build.properties fabric.properties # Editor-based Rest Client .idea/httpRequests # Android studio 3.1+ serialized cache file .idea/caches/build_file_checksums.ser *~ # temporary files which can be created if a process still has a handle open of a deleted file .fuse_hidden* # KDE directory preferences .directory # Linux trash folder which might appear on any partition or disk .Trash-* # .nfs files are created when an open file is removed but is still being accessed .nfs*
Once we have finished creating our file, we now need to configure Git to make use of it. We do so by using the following command
git config ---global core.excludesfile ~/.gitignore
These settings are now recognised and respected throughout all git repositories on your machine. However, the global gitignore file shouldn't be considered a great solution for all your collaborative repositories, because undoubtedly other developers on your team etc may not actually set this up or they may have a completely different settings as you.
What is a local .gitignore file
.gitignore file is usually placed in the root directory of a project and will contain project specific
settings pertaining to the files and directories you wish to exclude from your project.
Each line in a gitignore file specifies a pattern. When deciding whether to ignore a path, Git normally checks gitignore patterns from multiple sources, with the following order of precedence, from highest to lowest.
Patterns read from a .gitignore file in the same directory as the path, or in any parent directory, with patterns in the higher level files (up to the toplevel of the work tree) being overridden by those in lower level files down to the directory containing the file. These patterns match relative to the location of the .gitignore file. A project normally includes such .gitignore files in its repository, containing patterns for files generated as part of the project build.
How to create a local .gitignore file
The process of creating a local gitignore file is the same as creating is similar to the global gitignore, in that you just create a text based file named .gitignore file in your project directory. Then include the settings you wish. However, personally I find the process of creating gitignore files tedious and boring and like all programmers should I have created an automated process to accomplish this task.
As we mentioned earlier Githib provides a collection of useful .gitignore templates to use for creating your gitignore file. By making use of a simple Curl command to download the version of gitignore file we want from the repository. For instance if want to create a typical .gitignore for a NodeJS project we simply execute the following command in our terminal window
curl -o .gitignore https://raw.githubusercontent.com/github/gitignore/master/Node.gitignore
This will download the Node.gitIgnore file to our directory and save it as
.gitignore. If we inspect the content
of this file it contains the all the typical gitignore rules for NodeJS based projects.
# Logs logs *.log npm-debug.log* yarn-debug.log* yarn-error.log* lerna-debug.log* # Diagnostic reports (https://nodejs.org/api/report.html) report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json # Runtime data pids *.pid *.seed *.pid.lock # Directory for instrumented libs generated by jscoverage/JSCover lib-cov # Coverage directory used by tools like istanbul coverage *.lcov # nyc test coverage .nyc_output # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) .grunt # Bower dependency directory (https://bower.io/) bower_components # node-waf configuration .lock-wscript # Compiled binary addons (https://nodejs.org/api/addons.html) build/Release # Dependency directories node_modules/ jspm_packages/ # Snowpack dependency directory (https://snowpack.dev/) web_modules/ # TypeScript cache *.tsbuildinfo # Optional npm cache directory .npm # Optional eslint cache .eslintcache # Microbundle cache .rpt2_cache/ .rts2_cache_cjs/ .rts2_cache_es/ .rts2_cache_umd/ # Optional REPL history .node_repl_history # Output of 'npm pack' *.tgz # Yarn Integrity file .yarn-integrity # dotenv environment variables file .env .env.test # parcel-bundler cache (https://parceljs.org/) .cache .parcel-cache # Next.js build output .next out # Nuxt.js build / generate output .nuxt dist # Gatsby files .cache/ # Comment in the public line in if your project uses Gatsby and not Next.js # https://nextjs.org/blog/next-9-1#public-directory-support # public # vuepress build output .vuepress/dist # Serverless directories .serverless/ # FuseBox cache .fusebox/ # DynamoDB Local files .dynamodb/ # TernJS port file .tern-port # Stores VSCode versions used for testing VSCode extensions .vscode-test # yarn v2 .yarn/cache .yarn/unplugged .yarn/build-state.yml .yarn/install-state.gz .pnp.*
Using this command with the name of your preferred programming language can download typical settings required for that language.
## The language name passed in should follow the naming convention listed in the file name available ## https://github.com/github/gitignore curl -o .gitignore https://raw.githubusercontent.com/github/gitignore/master/<Programming Language here>.gitignore
How to add your own entries to gitignore
On occasion you may want to add additional rules to your gitignore file and this is very easy to do so and there are just a few things you need to know regarding the syntax used in gitignore files
The entries in this file can also follow a matching pattern.
*is used as a wildcard match
/is used to ignore path names relative to the .gitignore file
#is used to add comments to a .gitignore file
Some typical examples of implementing rules may be:
# Ignore the node_modules folder in the project directory node_modules ## Ignore all named local environment variable files i.e. .env.development.local etc .env.**.local ## Ignore all files in the .cache folder .cache/ ## ignore all files in the temp folder in src folder with a .tmp extension but include others src/temp/**.tmp
Which types of file should be ignored?
Typically, you should never track automatically generated files, i.e. files generated by the build system of a project. The reason for this is there is a high chance they will get out of sync with their source, they are not necessary and are always re-generated anyway.
Temporary files and by-products specific to a user's tool chain, should also not be included as tracked files.