5

Why would a developer commit a .dist file instead of the actual file?

For example: https://github.com/FriendsOfPHP/PHP-CS-Fixer

.php_cs.dist
phpunit.xml.dist

https://github.com/symfony/symfony

.php_cs.dist
phpunit.xml.dist

Why are .php_cs and phpunit.xml committed as .dist files?

Code formatting rules are in .php_cs.dist and if every contributor should follow the same rules why .dist file?

Update

Reasoning behind parameter.yml.dist is obvious but why in particular .php_cs is not committed? Why somebody would change the .php_cs which contains code formatting rules? isn't the whole point of .php_cs that every contributor use same rules to format their code?

Please reply regards to only these two files.

max630
  • 8,762
  • 3
  • 30
  • 55
pmoubed
  • 3,842
  • 10
  • 37
  • 60
  • See [my answer to a somewhat different question](https://stackoverflow.com/a/46134516/1256452). – torek Sep 09 '17 at 21:26
  • ".dist" usually means "this file is fit for distribution, but not for actual usage". This means that this is a template file, the actual file is probably ignored in that repository as well. Locally, after cloning, you should make a copy of the .dist file, removing the .dist part, and make your appropriate changes to it to make the software run on your system. – Lasse V. Karlsen Sep 09 '17 at 21:42
  • Reasoning behind parameter.yml.dist is obvious but why in particular .php_cs is not committed? Why somebody would change the .php_cs which contains code formatting rules? isn't the whole point of .php_cs that every contributor use same rules to format their code? – pmoubed Sep 09 '17 at 23:37

4 Answers4

4

You can see .dist files as template files. On your specific distribution, the configuration might be slightly different. Using the dist files, you can simply copy them to e.g. phpunit.xml and tweak it to fit your needs. (e.g. set some specific ENV variables or the like).

Little side-note: Another common dist file in Symfony projects is app/config/parameters.yml.dist

Wouter J
  • 41,455
  • 15
  • 107
  • 112
  • 1
    Reasoning behind parameter.yml.dist is obvious but why in particular .php_cs is not committed? Why somebody would change the .php_cs which contains code formatting rules? isn't the whole point of .php_cs that every contributor use same rules to format their code? – pmoubed Sep 09 '17 at 23:41
2

I found my answer here: https://github.com/symfony/recipes/issues/41

the difference is that PHPUnit will load the phpunit.xml.dist file if phpunit.xml does not exist. So you don't need to copy it unless you want to do special stuff. So committing a phpunit.xml.dist in the repo (and adding phpunit.xml in the gitignore) is just about following the PHPUnit best practice

The reason behind .dist file for those specific files is phpunit and php-cs-fixer use .dist file in absence of the local file.

pmoubed
  • 3,842
  • 10
  • 37
  • 60
0

Because doing so you make a difference between your local (often "dev") and distant configuration. This also allow you to protect your private datas without forgetting to set a required parameter.

For example, symfony has a "parameters.yml" file, and a "parameters.yml.dist" file. Your parameters contains real data, used for your actual environnment and is never commited if you respect good practices, because you would then push a file containing your database name, username, your mail host, and all kind of absolutely sensitive datas (secret token used in forms aswell).

So, you have a dist file, containing the same key, but without value :

Example : parameters.yml :

# This file is auto-generated during the composer install
parameters:
    database_host: mysql
    database_port: null
    database_name: portfolio
    database_user: artandor
    database_password: supersecretpassword
    mailer_transport: smtp
    mailer_host: smtp.gmail.com
    mailer_user: artandor
    mailer_password: supersecretaswell
    secret: 070950937b085d66fb1c59978ab9c47d4a420e32

and your dist file would look like :

# This file is a "template" of what your parameters.yml file should look like
# Set parameters here that may be different on each deployment target of the app, e.g. development, staging, production.
# https://symfony.com/doc/current/best_practices/configuration.html#infrastructure-related-configuration
parameters:
    database_host: 127.0.0.1
    database_port: ~
    database_name: symfony
    database_user: root
    database_password: ~
    # You should uncomment this if you want to use pdo_sqlite
    #database_path: '%kernel.project_dir%/var/data/data.sqlite'

    mailer_transport: smtp
    mailer_host: 127.0.0.1
    mailer_user: ~
    mailer_password: ~

    # A secret key that's used to generate certain security-related tokens
    secret: ThisTokenIsNotSoSecretChangeIt

Sorry for long post, wanted to make it clear for you :)

Usual process is pushing dist file, then once you pulled it on your server, make cp parameters.yml.dist parameters.yml

Other reason than securing datas, would be to have a different config between local and deployed application.

Bye :)

Artandor
  • 472
  • 6
  • 20
  • Reasoning behind parameter.yml.dist is obvious but why in particular .php_cs is not committed? Why somebody would change the .php_cs which contains code formatting rules? isn't the whole point of .php_cs that every contributor use same rules to format their code? – pmoubed Sep 09 '17 at 23:37
  • I'm not sure about this specific example, but considering there are a lot of rules and standards in code writting, i think this allow people to format the code to fit their habits ; while still providing a "recommended" format (contained in the dist file). You can also reverse this : the guy commiting doesn't like to write his code with the default rules, he uses his prefered one with his own config, but doesn't push it, so you get a clean config file. – Artandor Sep 10 '17 at 16:17
0

It is the same reason for php_cs.dist, you can local php_cs to customize rules, files and directories that need to be analyzed instead of using command line options to customize the rule and more : for example The --dry-run option displays the files that need to be fixed but without actually modifying them:

$ php php-cs-fixer.phar fix /path/to/code --dry-run

ect of options available here and can be sets in .php_cs local file.

T. Abdelmalek
  • 418
  • 3
  • 10