Difference between composer prefer-dist and prefer-source?

Looking at the help for PHP Composer's install command, I see the following two options

$ composer help install
Options:
 --prefer-source            Forces installation from package sources when possible, including VCS information.
 --prefer-dist              Forces installation from package dist even for dev versions.

What's a "dist" installation? I poked around the composer site and Google but there didn't seem to be anything that addressed this (So I assume it's something core and obvious to folks familiar with Composer — apologies for the newbie question)

I'm assuming --prefer-source is where Composer will ask Packagist for the repository location, and then checkout/clone/export/etc. the project itself.

If so, then where does --prefer-dist download from? What does it download?

According to http://getcomposer.org/doc/03-cli.md, the --prefer-source option will prefer to create a package directory that is a "version control repository". This is equivalent to you typing:

$ git clone ...

or

$ svn checkout ...

The --prefer-dist option will prefer to create a non-"version control repository", which is equivalent to you typing:

$ git clone ... ; rm -fr dir/.git

or

$ svn export ...

Also, you can define separate repos for source and dist in your composer.json. Here's an example:

{
    "repositories": [
    	{
            "type": "package",
            "package": {
                "name": "joshuaclayton/blueprint-css",
                "version": "master",
                "source": {
                    "url": "git://github.com/joshuaclayton/blueprint-css.git",
                    "type": "git",
                    "reference": "master",
                }
            }
        },
        {
            "type": "package",
            "package": {
                "name": "fiftyone/mobi-lite-php",
                "version": "2013.03.06",
                "dist": {
                    "url": "http://iweb.dl.sourceforge.net/project/fiftyone/51Degrees.mobi-Lite-2013.03.06.php.zip",
                    "type": "zip"
                },
            }
        }
	]
}

NOTE: for whatever reason, when I use --prefer-dist, I sometimes get errors such as

Fatal error: Cannot redeclare class Zend_Db_Adapter_Pdo_Abstract in ...

which do not appear when I use --prefer-source. For this reason, I only use --prefer-source, until I figure out the cause of this issue.

I don't admire, or even approve the provided answer, as it does not address the question. So despite of it being a bit too old, I am posting this answer for any further reference to this question.

---

Basics:

Normally composer deals with tags (like 1.2.7), but that is not the case all the time. You may also require a branch (like dev-master) as a dependency.

• If you want composer to require a tag, it just copies the files on your local (somewhere in your vendor directory).

• If you want composer to checkout a branch instead of a tag, there is chance (composer's rational assumption), you want to develop it (thus making changes), so composer clones the repository on your local (again, somewhere in the vendor directory).

---

So, what?!

Question:

What if you want to require a tag, but still be able to develop it on your local?

Answer:

use --prefer-source along with your composer require or composer update commands:

composer require symfony/symfony:3.4.* --prefer-source

Question:

What if you want to require a most new development branch, but you just want to get the new stuff and don't want to get engaged in its development?

Answer:

use --prefer-dist along with your composer require, composer update commands:

composer require symfony/symfony:dev-master --prefer-dist

As clearly stated in Composer's Documentation:

>In fact, internally Composer sees every version as a separate package. While this distinction does not matter when you are using Composer, it's quite important when you want to change it.

and, >Dist: The dist is a packaged version of the package data. Usually a released version, usually a stable release. > >Source: The source is used for development. This will usually originate from a source code repository, such as git. You can fetch this when you want to modify the downloaded package.

so, >Packages can supply either of these, or even both. Depending on certain factors, such as user-supplied options and stability of the package, one will be preferred.

If you're checking out a branch, it's assumed that you want to work on the branch and Composer actually clones the repo into the correct place in your vendor directory.

For tags, it just copies the right files without actually cloning the repo.