You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
96 lines
3.6 KiB
Markdown
96 lines
3.6 KiB
Markdown
<!--
|
|
tagline: Alias branch names to versions
|
|
-->
|
|
|
|
# Aliases
|
|
|
|
## Why aliases?
|
|
|
|
When you are using a VCS repository, you will only get comparable versions for
|
|
branches that look like versions, such as `2.0`. For your `master` branch, you
|
|
will get a `dev-master` version. For your `bugfix` branch, you will get a
|
|
`dev-bugfix` version.
|
|
|
|
If your `master` branch is used to tag releases of the `1.0` development line,
|
|
i.e. `1.0.1`, `1.0.2`, `1.0.3`, etc., any package depending on it will
|
|
probably require version `1.0.*`.
|
|
|
|
If anyone wants to require the latest `dev-master`, they have a problem: Other
|
|
packages may require `1.0.*`, so requiring that dev version will lead to
|
|
conflicts, since `dev-master` does not match the `1.0.*` constraint.
|
|
|
|
Enter aliases.
|
|
|
|
## Branch alias
|
|
|
|
The `dev-master` branch is one in your main VCS repo. It is rather common that
|
|
someone will want the latest master dev version. Thus, Composer allows you to
|
|
alias your `dev-master` branch to a `1.0.x-dev` version. It is done by
|
|
specifying a `branch-alias` field under `extra` in `composer.json`:
|
|
|
|
{
|
|
"extra": {
|
|
"branch-alias": {
|
|
"dev-master": "1.0.x-dev"
|
|
}
|
|
}
|
|
}
|
|
|
|
The branch version must begin with `dev-` (non-comparable version), the alias
|
|
must be a comparable dev version (i.e. start with numbers, and end with
|
|
`.x-dev`). The `branch-alias` must be present on the branch that it references.
|
|
For `dev-master`, you need to commit it on the `master` branch.
|
|
|
|
As a result, anyone can now require `1.0.*` and it will happily install
|
|
`dev-master`.
|
|
|
|
In order to use branch aliasing, you must own the repository of the package
|
|
being aliased. If you want to alias a third party package without maintaining
|
|
a fork of it, use inline aliases as described below.
|
|
|
|
## Require inline alias
|
|
|
|
Branch aliases are great for aliasing main development lines. But in order to
|
|
use them you need to have control over the source repository, and you need to
|
|
commit changes to version control.
|
|
|
|
This is not really fun when you just want to try a bugfix of some library that
|
|
is a dependency of your local project.
|
|
|
|
For this reason, you can alias packages in your `require` and `require-dev`
|
|
fields. Let's say you found a bug in the `monolog/monolog` package. You cloned
|
|
Monolog on GitHub and fixed the issue in a branch named `bugfix`. Now you want
|
|
to install that version of monolog in your local project.
|
|
|
|
You are using `symfony/monolog-bundle` which requires `monolog/monolog` version
|
|
`1.*`. So you need your `dev-bugfix` to match that constraint.
|
|
|
|
Just add this to your project's root `composer.json`:
|
|
|
|
{
|
|
"repositories": [
|
|
{
|
|
"type": "vcs",
|
|
"url": "https://github.com/you/monolog"
|
|
}
|
|
],
|
|
"require": {
|
|
"symfony/monolog-bundle": "2.0",
|
|
"monolog/monolog": "dev-bugfix as 1.0.x-dev"
|
|
}
|
|
}
|
|
|
|
That will fetch the `dev-bugfix` version of `monolog/monolog` from your GitHub
|
|
and alias it to `1.0.x-dev`.
|
|
|
|
> **Note:** If a package with inline aliases is required, the alias (right of
|
|
> the `as`) is used as the version constraint. The part left of the `as` is
|
|
> discarded. As a consequence, if A requires B and B requires `monolog/monolog`
|
|
> version `dev-bugfix as 1.0.x-dev`, installing A will make B require
|
|
> `1.0.x-dev`, which may exist as a branch alias or an actual `1.0` branch. If
|
|
> it does not, it must be re-inline-aliased in A's `composer.json`.
|
|
|
|
> **Note:** Inline aliasing should be avoided, especially for published
|
|
> packages. If you found a bug, try and get your fix merged upstream. This
|
|
> helps to avoid issues for users of your package.
|