1<!--
2    tagline: Alias branch names to versions
3-->
4
5# Aliases
6
7## Why aliases?
8
9When you are using a VCS repository, you will only get comparable versions for
10branches that look like versions, such as `2.0` or `2.0.x`. For your `master` branch, you
11will get a `dev-master` version. For your `bugfix` branch, you will get a
12`dev-bugfix` version.
13
14If your `master` branch is used to tag releases of the `1.0` development line,
15i.e. `1.0.1`, `1.0.2`, `1.0.3`, etc., any package depending on it will
16probably require version `1.0.*`.
17
18If anyone wants to require the latest `dev-master`, they have a problem: Other
19packages may require `1.0.*`, so requiring that dev version will lead to
20conflicts, since `dev-master` does not match the `1.0.*` constraint.
21
22Enter aliases.
23
24## Branch alias
25
26The `dev-master` branch is one in your main VCS repo. It is rather common that
27someone will want the latest master dev version. Thus, Composer allows you to
28alias your `dev-master` branch to a `1.0.x-dev` version. It is done by
29specifying a `branch-alias` field under `extra` in `composer.json`:
30
31```json
32{
33    "extra": {
34        "branch-alias": {
35            "dev-master": "1.0.x-dev"
36        }
37    }
38}
39```
40
41If you alias a non-comparable version (such as dev-develop) `dev-` must prefix the
42branch name. You may also alias a comparable version (i.e. start with numbers,
43and end with `.x-dev`), but only as a more specific version.
44For example, 1.x-dev could be aliased as 1.2.x-dev.
45
46The alias must be a comparable dev version, and the `branch-alias` must be present on
47the branch that it references. For `dev-master`, you need to commit it on the
48`master` branch.
49
50As a result, anyone can now require `1.0.*` and it will happily install
51`dev-master`.
52
53In order to use branch aliasing, you must own the repository of the package
54being aliased. If you want to alias a third party package without maintaining
55a fork of it, use inline aliases as described below.
56
57## Require inline alias
58
59Branch aliases are great for aliasing main development lines. But in order to
60use them you need to have control over the source repository, and you need to
61commit changes to version control.
62
63This is not really fun when you just want to try a bugfix of some library that
64is a dependency of your local project.
65
66For this reason, you can alias packages in your `require` and `require-dev`
67fields. Let's say you found a bug in the `monolog/monolog` package. You cloned
68[Monolog](https://github.com/Seldaek/monolog) on GitHub and fixed the issue in
69a branch named `bugfix`. Now you want to install that version of monolog in your
70local project.
71
72You are using `symfony/monolog-bundle` which requires `monolog/monolog` version
73`1.*`. So you need your `dev-bugfix` to match that constraint.
74
75Just add this to your project's root `composer.json`:
76
77```json
78{
79    "repositories": [
80        {
81            "type": "vcs",
82            "url": "https://github.com/you/monolog"
83        }
84    ],
85    "require": {
86        "symfony/monolog-bundle": "2.0",
87        "monolog/monolog": "dev-bugfix as 1.0.x-dev"
88    }
89}
90```
91
92That will fetch the `dev-bugfix` version of `monolog/monolog` from your GitHub
93and alias it to `1.0.x-dev`.
94
95> **Note:** If a package with inline aliases is required, the alias (right of
96> the `as`) is used as the version constraint. The part left of the `as` is
97> discarded. As a consequence, if A requires B and B requires `monolog/monolog`
98> version `dev-bugfix as 1.0.x-dev`, installing A will make B require
99> `1.0.x-dev`, which may exist as a branch alias or an actual `1.0` branch. If
100> it does not, it must be re-inline-aliased in A's `composer.json`.
101
102> **Note:** Inline aliasing should be avoided, especially for published
103> packages. If you found a bug, try and get your fix merged upstream. This
104> helps to avoid issues for users of your package.
105