All WordPress Developers Need To Know About .gitattributes

When you use Git in your WordPress deployment flow, there is a special configuration file you should be aware of. .gitattributes can drastically clean up your plugins and themes for end users. Follow along and I will show you how simple it is to use.

The good news

In most cases, actually “all” you need to know is only one thing. Namely, how to clean up your packages and not bother your end users with files they do not care about. First, let me briefly go over what .gitattributes is and what you can do with it.

In brief, .gitattributes is a Git configuration file that lets you configure path-specific settings, ie. for specific directories and files. These settings include advanced features such as filtering the content of files before committing changes and configuring path-specific merge strategies. Most probably, you will never have to do this. However, other features, more relevant to “normal” users, include configuring repository exports and normalising file line endings. The latter is easily achieved with just one line of code: * text=auto. This will, according to GitHub, let Git “… handle the files in whatever way it thinks is best“, so let’s roll with that. You should always have this line in you .gitattributes, to prevent team mates from committing line ending noise.

If you want to create a very basic .gitattributes to get started, you can copy this:

* text=auto

/.gitattributes export-ignore

That last line is important!

Exporting repositories

Git’s export feature lets you convert a Git repository into a tar- or zipball. The behaviour of this can be configured via the .gitattributes file. This feature is what GitHub and Bitbucket uses to let you download a zip archive with your repository’s content. This is cool, because WP Pusher downloads your code in .zip format from these services.

You can do two things with files in your repository before an export: 1. your can modify them, by substituting parts of the content, or 2. you can ignore them. The latter one is great for deployment and you should always be doing this – or at least make a conscious decisions about it. Basically, the last line in the file I just showed you tells Git not to include the .gitattributes file in the exported repository. This is smart, because my end users have no desire to download my Git configuration files when they use one of my packages.

This is how the .gitattributes file looks for WP Pusher:

/features       export-ignore
/.gitattributes export-ignore
/.gitignore     export-ignore
/apache-ci.conf export-ignore
/behat.yml      export-ignore
/circle.yml     export-ignore
/composer.json  export-ignore
/composer.lock  export-ignore

These are all the files that I use when developing WP Pusher that are useless to end users. There is no need to ship my configuration files and unit tests with the plugin, so these should be ignored. Before adding a .gitattributes file to the repository, I deleted these file manually before shipping a new version.


Want to read more like this?

Add your email address below to stay in the loop when new content arrives. You'll never miss a post.

Peter Suhm

Peter is a web developer from the Land of the Danes. He is the creator of WP Pusher and a huge travel addict.