Using .gitattributes in package distribution in GitHub

Hi there, how’s it going? This is the second time to write the entry in English for me.

Anyway, do you know or have you ever used the .gitattributes file in package distribution in GitHub using its Release feature?
OK, for those people who don’t/haven’t that, let me explain a brief.
This is the meta data file where you can add some attributes to the files version-controlled by Git.

What the attributes are

The Official Git document descripting attributes is providing us the nice example, saying:

Using attributes, you can do things like specify separate merge strategies for individual files or directories in your project, tell Git how to diff non-text files, or have Git filter content before you check it into or out of Git.

That’s easier to figure out. For example, if you write down your .gitattributes like this:

config.yml merge=ours

It’s using a merge attribute for config.yml to tell Git what the merge driver to be used for the file. In this case, it’s our. our doesn’t make any sense but just the name of the driver. Of course, originally you may don’t have the driver named our I guess. So following configuration is needed to run this magic:

$ git config --global merge.ours.driver true

That’s it. Now the driver our is specified as true. true is built-in command just returning exit-code 0 with doing nothing.
So the conclusion is when you merge some branch into your branch, your changes applied to config.yml is always adapted to ship to a commit even though any conflicts with other branch occurs, with no confirmation.

For example, this may be useful the situation where you fork some nice repository and maintain it your own but you don’t want to apply any changes to the specific file (config.yml) during even back-porting changes for the original which happens sometimes.

Also, the attributes can also be applied to the directory, in that case, the attributes should apply to subfiles in the directory.

Moreover, there are many other kinds of attributes in Git, but I don’t pick them up anymore for keeping my topic (other than one I’ll share you below). So check the document out if you’re interested 🙂

export-ignore attribute

So Git also has an attribute export-ignore. The files which are applied this attribute should NOT be included in archive.

For example:

/tests export-ignore
README.md export-ignore

This prevents the /test directory and README.md from including to the archive. The archive? The one which can be generated by:

$ git archive HEAD --worktree-attributes --output=/tmp/repo.zip

TIP: don’t forget --worktree-attributes command option. Although it’s not necessary, the exclusion doesn’t work if you don’t specify it.

It’s good and useful, isn’t it? In script languages such PHP, the distributed packages don’t need to include the tests stuff. Nobody wants to install/deploy them to their production server.
And GitHub resources feature use this attribute to archive in their Release feature.
So that’s why you should always setup your export-ignore attribute for your package powered by GitHub Release (e.g. Packagist package for PHP).

Conclusion

• The files specified attribute export-ignore in .gitattributes are not to be archived
• GitHub Release feature archives the repository using this attribute, so you can avoid shipping some unnecessary kinds like tests stuff for production

We’re hiring!

We’re hiring the software engineer who can work remotely. No matter country you live, and although we’re a Japanese company, non Japanese speaker is acceptable! (required English)
Please see here for your information and feel free in touch us if you’re interested! (We now don’t have the Japanese recruit page but now preparing it. We apologize for the inconvenience)