Always use caret instead of tilde

I’ve been noticing people having trouble understanding the differences between the caret (“^”) and the tilde (“~”) operator in the composer.json file. Composer’s documentation is great but a bit short, that is why I write this blog post.

Composer assumes that all packages are using Semver. It is an easy version schema that consists of a major.minor.patch version. A major version breaks backwards compatibility, minor version introduces new features and patch versions are bug fixes.

The tilde operator is best explained by example. Notice that it actually makes a difference if you specify the patch version or not.

~1.0   means >=1.0.0 <2.0.0 same as 1.*
~1.0.0 means >=1.0.0 <1.1.0 same as 1.0.*

The caret operator follows Semver.


^1.0   means >=1.0.0 <2.0.0 same as 1.*
^1.0.0 means >=1.0.0 <2.0.0 same as 1.*

What is little less known is that Semver behaves differently on versions under 1.0.0. Before the project has a stable release, minor versions are allowed to break backwards compatibility. This is dangerous when you use the tilde operator since you may get update that breaks backwards compatibility.

// This is dangerous as updates might break BC
~0.2 means >=0.2.0 <1.0.0

// This is fine
~1.2 means >=1.2.0 <2.0.0

A workaround for this could be that you always specify versions under 1.0.0 with an asterisk (“*”).

0.2.* means >=0.2.0 <0.3.0

A better approach is to continue to use the caret operator as it still respects Semver even on versions under 1.0.0.

^0.2 means >=0.2.0 <0.3.0

In conclusion: One should always use caret (“^”) over tilde (“~”) because caret is always respecting Semver.

2 Comments

  1. Take that conclusion with a grain of salt. Not all packages are following semver, in those cases, a tilde can be useful.

    Reply
  2. Nice reading Tobias – I’ve forwarded the link to a couple of colleagues.

    Reply

Trackbacks/Pingbacks

  1. August 2016 Newsletter - Nomad PHP - […] Always Use Caret instead of Tilde Tobias Nyholm […]

Leave a Reply to Jeroen Noten Cancel reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>