Dotfiles for crossplatform projects

Whenever I start a new project, I like to check in configurations to Git, so that every other developer uses the same settings as I do. This also leads to more reproducible build.

This post summarizes the different files and their interdependencies. For me it provides a copy-and-paste resource for my projects. For you it might be a starting point for you own project.

I acknowledge that this is not the first dot-files-guide, there have been others – I like Mathias' repo very much – and I assume mine will not be the last.

The setup is opinionated, your mileage may vary. The projects I work in often look like this:

  • Development is a mixed Windows, Linux and MacOS environment
  • Sometimes a virtual machine running Linux (Vagrant/Virtual Box) mounts the files using a shared folder from a Windows host
  • Build automation runs on Linux, usually with Jenkins
  • My IDE is IntelliJ

EditorConfig

The EditorConfig is a file called .editorconfig in the root of the project. You can specify how your editor should handle your files. IntelliJ has built-in support for this configuration files.

.editorconfig
# EditorConfig is awesome: http://EditorConfig.org

# This is the file in the root of the project.
# For sub folders you can have other files that override only some settings.
# For these, this settings should be false.
root = true

[*]
max_line_length = 120
# For me it's spaces, not tabs.
indent_style = space
indent_size = 4
continuation_indent_size = 8
# I follow Linux conventions here.
# This needs to match the setting in .gitsettings, otherwise you'll have
# files with crlf due to Git, that will be converted by your IDE to lf and this
# shows up as local changes :-(
end_of_line = lf
# This should match the settings in your build tools.
# Especially useful when I write AsciiDoc documentation.
charset = utf-8
# Trimming is good for consistency!
trim_trailing_whitespace = true
# I've seen cases where a missing new_line was ignored on *nix systems.
# Never again with this setting!
insert_final_newline = true

[*.properties]
# There is always an exception to a rule:
# Java properties files should be encoded latin1 (aka iso8859-1)
charset = latin1

[*.{cmd,bat}]
# batch files on Windows should stay with CRLF
end_of_line = crlf

Git Attributes

This file is called .gitattributes and resides in the root folder of your project. This tells Git how to treat line endings and binary files.

The line ending settings need to match your Editorconfig.

.gitattributes
# To match the .editorconfig that asks for lf only
# Otherwise you will end up with files that show up as modified after you IDE
* text=auto eol=lf

# Shell scripts need to be LF when you run them on *inux.
# The mvnw is the Maven wrapper file, gradlew the Gradle wrapper file.
*.sh text eol=lf
/mvnw text eol=lf
/gradlew text eol=lf
*.cmd text eol=crlf

# Denote all files that are truly binary and should not be modified.
*.png binary
*.jpg binary

Note that changing these settings doesn’t affect your working directory. You’ll need to perform a reset on a clean working tree as the following command will discard any uncommitted changes. See "How to normalize working tree line endings in Git?" on StackOverflow.

git rm --cached -r .
git reset --hard

Git Ignore

This file is called .gitignore and resides in the root folder of your project. Subfolders can have additional .gitignore files that can extend and override these settings.

The files to ignore depend on the IDE build tools you use. Here the most common I use.

For more information about the required plugins feature in IntelliJ, visit the section “Required Plugins” in the chapter “Manage plugins” in the IntelliJ online help.

.gitignore
### Intellij ###
# Ignore the IntelliJ standard folder with configurations
/.idea/*
*.iml
# These are the run configurations you marked as "shared"
# This allows you to share them with fellow developers.
!/.idea/runConfigurations
# This allows you to check-in data sources for other developers to use
!/.idea/dataSources.xml
# This allows you to check-in the Checkstyle configurations in IntelliJ
!/.idea/checkstyle-idea.xml
# You can configure your IntelliJ project settings to prompt fellow developers
# to install required plugins.
# Once you use this, check in the file created by the IDE.
!/.idea/externalDependencies.xml

### Eclipse ###
/.classpath
/.project
/.settings/

### Gradle ###
.gradle
build/
lib/

### Maven ###
target/
*.releaseBackup
release.properties
*-reduced-pom.xml

Maven

The most important bit is to match the file encoding that is also used in .editorconfig.

<project>
  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <!-- ... -->
  </properties>
  <!-- ... -->
</project>

I hope this will help you in new and existing projects like it helps me.

I’m looking forward to your feedback - contact me!

Back to overview...