From 011e0f0d45d426456ffe79a533a529a0e4ce010e Mon Sep 17 00:00:00 2001 From: Nic Wortel Date: Sat, 3 May 2014 19:12:31 +0200 Subject: [PATCH 01/10] Update .gitignore example As confirmed by WouterJ on Stack Overflow [1], the example .gitignore file [2] is not up-to-date. This commit updates the documentation to reflect the current state of the .gitignore file that is included in the Symfony Standard Edition distribution [3]. [1] http://stackoverflow.com/q/23437768/1001110 [2] http://symfony.com/doc/current/cookbook/workflow/new_project_git.html#initial-project-setup [3] https://github.com/symfony/symfony-standard/blob/master/.gitignore --- cookbook/workflow/new_project_git.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/cookbook/workflow/new_project_git.rst b/cookbook/workflow/new_project_git.rst index f0403af21a1..8d81ff42da0 100644 --- a/cookbook/workflow/new_project_git.rst +++ b/cookbook/workflow/new_project_git.rst @@ -32,11 +32,16 @@ git repository: .. code-block:: text /web/bundles/ - /app/bootstrap* + /app/bootstrap.php.cache /app/cache/* + /app/config/parameters.yml /app/logs/* + !app/cache/.gitkeep + !app/logs/.gitkeep + /build/ /vendor/ - /app/config/parameters.yml + /bin/ + /composer.phar .. tip:: From 34d61eb4e03399fe1b8c1632d0d439386c6a4b76 Mon Sep 17 00:00:00 2001 From: Nic Wortel Date: Sun, 4 May 2014 15:54:50 +0200 Subject: [PATCH 02/10] Update the complete 'Initial Project Setup' paragraph As proposed by WouterJ in https://github.com/symfony/symfony-docs/pull/3827 this commit rewrites the 'Initial Project Setup' paragraph. The documentation now describes the recommended way of creating a new Symfony2 project, using Composer to download the Standard Distribution + vendors (instead of downloading the zipped version). As the Standard Edition already contains a .gitignore, the example is replaced by a link to the one stored at GitHub. The article also explains which files are excluded by .gitignore. The last step (downloading vendor libraries using Composer) is removed as this is now covered by step 1. --- cookbook/workflow/new_project_git.rst | 49 ++++++++++++++------------- 1 file changed, 25 insertions(+), 24 deletions(-) diff --git a/cookbook/workflow/new_project_git.rst b/cookbook/workflow/new_project_git.rst index 8d81ff42da0..03e94345f21 100644 --- a/cookbook/workflow/new_project_git.rst +++ b/cookbook/workflow/new_project_git.rst @@ -20,28 +20,30 @@ Initial Project Setup To get started, you'll need to download Symfony and initialize your local git repository: -1. Download the `Symfony2 Standard Edition`_ without vendors. +1. Download the `Symfony2 Standard Edition`_ using Composer: -2. Unzip/untar the distribution. It will create a folder called Symfony with - your new project structure, config files, etc. Rename it to whatever you like. + .. code-block:: bash + + $ php composer.phar create-project symfony/framework-standard-edition path/ 2.4.4 -3. Create a new file called ``.gitignore`` at the root of your new project - (e.g. next to the ``composer.json`` file) and paste the following into it. Files - matching these patterns will be ignored by Git: + Composer will now download the Standard Distribution along with all of the + required vendor libraries. For more information about downloading Symfony using + Composer, see `Installing Symfony using Composer`_. - .. code-block:: text +2. Your project folder will now contain files of the Symfony framework, as well + as files and folders for vendor libraries. You'll want to store your project + files in Git, but not the dependencies, since they will be managed by Composer. + You'll also want to keep your ``parameters.yml`` out of your repository as it will + contain sensitive information, such as database credentials. Furthermore, + files that are automatically created by Symfony (such as logs, caches, and dumped + assets) should be excluded as well. - /web/bundles/ - /app/bootstrap.php.cache - /app/cache/* - /app/config/parameters.yml - /app/logs/* - !app/cache/.gitkeep - !app/logs/.gitkeep - /build/ - /vendor/ - /bin/ - /composer.phar + To help you keep these files out of your repository, Symfony comes with a file + called ``.gitignore``. It contains a list of files and folders that Git will + ignore. + + The contents of the ``.gitignore`` file that comes with the Standard Distribution + can be found in the `GitHub repository`_. .. tip:: @@ -49,27 +51,24 @@ git repository: in which case, you can find more information here: `Github .gitignore`_ This way you can exclude files/folders often used by your IDE for all of your projects. -4. Initialize your Git repository: +3. Initialize your Git repository: .. code-block:: bash $ git init -5. Add all of the initial files to Git: +4. Add all of the initial files to Git: .. code-block:: bash $ git add . -6. Create an initial commit with your started project: +5. Create an initial commit with your started project: .. code-block:: bash $ git commit -m "Initial commit" -7. Finally, download all of the third-party vendor libraries by - executing Composer. For details, see :ref:`installation-updating-vendors`. - At this point, you have a fully-functional Symfony2 project that's correctly committed to Git. You can immediately begin development, committing the new changes to your Git repository. @@ -116,6 +115,8 @@ manage this is `Gitolite`_. .. _`Git`: http://git-scm.com/ .. _`Symfony2 Standard Edition`: http://symfony.com/download +.. _`Installing Symfony using Composer`: http://symfony.com/doc/current/book/installation.html#option-1-composer +.. _`GitHub repository`: https://github.com/symfony/symfony-standard/blob/master/.gitignore .. _`git submodules`: http://git-scm.com/book/en/Git-Tools-Submodules .. _`GitHub`: https://github.com/ .. _`barebones repository`: http://git-scm.com/book/en/Git-Basics-Getting-a-Git-Repository From 6a196289f311c4f0b64025af27e906193a4776f6 Mon Sep 17 00:00:00 2001 From: Nic Wortel Date: Mon, 5 May 2014 20:22:09 +0200 Subject: [PATCH 03/10] Indent the tip to be on the same level as the list item --- cookbook/workflow/new_project_git.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cookbook/workflow/new_project_git.rst b/cookbook/workflow/new_project_git.rst index 03e94345f21..96e051abb9a 100644 --- a/cookbook/workflow/new_project_git.rst +++ b/cookbook/workflow/new_project_git.rst @@ -45,11 +45,11 @@ git repository: The contents of the ``.gitignore`` file that comes with the Standard Distribution can be found in the `GitHub repository`_. -.. tip:: + .. tip:: - You may also want to create a .gitignore file that can be used system-wide, - in which case, you can find more information here: `Github .gitignore`_ - This way you can exclude files/folders often used by your IDE for all of your projects. + You may also want to create a .gitignore file that can be used system-wide, + in which case, you can find more information here: `Github .gitignore`_ + This way you can exclude files/folders often used by your IDE for all of your projects. 3. Initialize your Git repository: From 311f14bf587db62821a42b7c3f974a034821b472 Mon Sep 17 00:00:00 2001 From: Nic Wortel Date: Mon, 5 May 2014 20:23:30 +0200 Subject: [PATCH 04/10] Replace numbered list items with # ...so we don't have to renumber them every time we remove/add a new item. --- cookbook/workflow/new_project_git.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/cookbook/workflow/new_project_git.rst b/cookbook/workflow/new_project_git.rst index 96e051abb9a..e7c59a30eb5 100644 --- a/cookbook/workflow/new_project_git.rst +++ b/cookbook/workflow/new_project_git.rst @@ -20,7 +20,7 @@ Initial Project Setup To get started, you'll need to download Symfony and initialize your local git repository: -1. Download the `Symfony2 Standard Edition`_ using Composer: +#. Download the `Symfony2 Standard Edition`_ using Composer: .. code-block:: bash @@ -30,7 +30,7 @@ git repository: required vendor libraries. For more information about downloading Symfony using Composer, see `Installing Symfony using Composer`_. -2. Your project folder will now contain files of the Symfony framework, as well +#. Your project folder will now contain files of the Symfony framework, as well as files and folders for vendor libraries. You'll want to store your project files in Git, but not the dependencies, since they will be managed by Composer. You'll also want to keep your ``parameters.yml`` out of your repository as it will @@ -51,19 +51,19 @@ git repository: in which case, you can find more information here: `Github .gitignore`_ This way you can exclude files/folders often used by your IDE for all of your projects. -3. Initialize your Git repository: +#. Initialize your Git repository: .. code-block:: bash $ git init -4. Add all of the initial files to Git: +#. Add all of the initial files to Git: .. code-block:: bash $ git add . -5. Create an initial commit with your started project: +#. Create an initial commit with your started project: .. code-block:: bash From 32cee81f3acf393a3324a4917c8eac49026c70d4 Mon Sep 17 00:00:00 2001 From: Nic Wortel Date: Tue, 13 May 2014 14:08:22 +0200 Subject: [PATCH 05/10] Small change in the wording ...as suggested by weaverryan. --- cookbook/workflow/new_project_git.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/workflow/new_project_git.rst b/cookbook/workflow/new_project_git.rst index e7c59a30eb5..1bf95850a85 100644 --- a/cookbook/workflow/new_project_git.rst +++ b/cookbook/workflow/new_project_git.rst @@ -30,7 +30,7 @@ git repository: required vendor libraries. For more information about downloading Symfony using Composer, see `Installing Symfony using Composer`_. -#. Your project folder will now contain files of the Symfony framework, as well +#. Your project folder will now contain files for your new project, as well as files and folders for vendor libraries. You'll want to store your project files in Git, but not the dependencies, since they will be managed by Composer. You'll also want to keep your ``parameters.yml`` out of your repository as it will From 083c1f52a953920f85439ff622b1e0ee9d4a68e3 Mon Sep 17 00:00:00 2001 From: Nic Wortel Date: Fri, 16 May 2014 08:52:04 +0200 Subject: [PATCH 06/10] Replace static version constraint (2.4.4) ...with a smarter one. Using Composer's tilde operator (~), also known as the next significant release constraint, we instruct composer to use at least Symfony 2.3, but not 3.0 or higher. --- cookbook/workflow/new_project_git.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/workflow/new_project_git.rst b/cookbook/workflow/new_project_git.rst index 1bf95850a85..16c2f21da31 100644 --- a/cookbook/workflow/new_project_git.rst +++ b/cookbook/workflow/new_project_git.rst @@ -24,7 +24,7 @@ git repository: .. code-block:: bash - $ php composer.phar create-project symfony/framework-standard-edition path/ 2.4.4 + $ php composer.phar create-project symfony/framework-standard-edition path/ ~2.3 Composer will now download the Standard Distribution along with all of the required vendor libraries. For more information about downloading Symfony using From d9f72f95087e6bdcbd06ce2f4613acc531e6dfe5 Mon Sep 17 00:00:00 2001 From: Nic Wortel Date: Fri, 16 May 2014 09:17:15 +0200 Subject: [PATCH 07/10] Some refactoring of the article Shorten the 2nd list item a bit, and move it into a 'Tip' seems to make more sense. --- cookbook/workflow/new_project_git.rst | 39 ++++++++++++--------------- 1 file changed, 17 insertions(+), 22 deletions(-) diff --git a/cookbook/workflow/new_project_git.rst b/cookbook/workflow/new_project_git.rst index 16c2f21da31..259df03dc9f 100644 --- a/cookbook/workflow/new_project_git.rst +++ b/cookbook/workflow/new_project_git.rst @@ -30,27 +30,6 @@ git repository: required vendor libraries. For more information about downloading Symfony using Composer, see `Installing Symfony using Composer`_. -#. Your project folder will now contain files for your new project, as well - as files and folders for vendor libraries. You'll want to store your project - files in Git, but not the dependencies, since they will be managed by Composer. - You'll also want to keep your ``parameters.yml`` out of your repository as it will - contain sensitive information, such as database credentials. Furthermore, - files that are automatically created by Symfony (such as logs, caches, and dumped - assets) should be excluded as well. - - To help you keep these files out of your repository, Symfony comes with a file - called ``.gitignore``. It contains a list of files and folders that Git will - ignore. - - The contents of the ``.gitignore`` file that comes with the Standard Distribution - can be found in the `GitHub repository`_. - - .. tip:: - - You may also want to create a .gitignore file that can be used system-wide, - in which case, you can find more information here: `Github .gitignore`_ - This way you can exclude files/folders often used by your IDE for all of your projects. - #. Initialize your Git repository: .. code-block:: bash @@ -63,6 +42,23 @@ git repository: $ git add . + .. tip:: + + As you might have noticed, not all files that were downloaded by Composer in step 1, + have been staged for commit by Git. Certain files and folders, such as the project's + dependencies (which are managed by Composer), ``parameters.yml`` (which contains sensitive + information such as database credentials) and log-, cache- and asset files (which are + created automatically by your project), should not be committed in Git. To help you prevent + committing those files and folders by accident, the Standard Distribution comes with a + file called ``.gitignore``, which contains a list of files and folders that Git should + ignore. + + .. tip:: + + You may also want to create a .gitignore file that can be used system-wide, + in which case, you can find more information here: `Github .gitignore`_ + This way you can exclude files/folders often used by your IDE for all of your projects. + #. Create an initial commit with your started project: .. code-block:: bash @@ -116,7 +112,6 @@ manage this is `Gitolite`_. .. _`Git`: http://git-scm.com/ .. _`Symfony2 Standard Edition`: http://symfony.com/download .. _`Installing Symfony using Composer`: http://symfony.com/doc/current/book/installation.html#option-1-composer -.. _`GitHub repository`: https://github.com/symfony/symfony-standard/blob/master/.gitignore .. _`git submodules`: http://git-scm.com/book/en/Git-Tools-Submodules .. _`GitHub`: https://github.com/ .. _`barebones repository`: http://git-scm.com/book/en/Git-Basics-Getting-a-Git-Repository From 6fd5e5281effcf2579d9db0afe0fdb39b06bd555 Mon Sep 17 00:00:00 2001 From: Nic Wortel Date: Fri, 16 May 2014 09:22:57 +0200 Subject: [PATCH 08/10] Small improvement --- cookbook/workflow/new_project_git.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/workflow/new_project_git.rst b/cookbook/workflow/new_project_git.rst index 259df03dc9f..d41c50e781f 100644 --- a/cookbook/workflow/new_project_git.rst +++ b/cookbook/workflow/new_project_git.rst @@ -47,7 +47,7 @@ git repository: As you might have noticed, not all files that were downloaded by Composer in step 1, have been staged for commit by Git. Certain files and folders, such as the project's dependencies (which are managed by Composer), ``parameters.yml`` (which contains sensitive - information such as database credentials) and log-, cache- and asset files (which are + information such as database credentials), log- and cache files and dumped assets (which are created automatically by your project), should not be committed in Git. To help you prevent committing those files and folders by accident, the Standard Distribution comes with a file called ``.gitignore``, which contains a list of files and folders that Git should From 1baf7e0492d2de188cc53fd9541db09ed5c89e5f Mon Sep 17 00:00:00 2001 From: Nic Wortel Date: Mon, 19 May 2014 10:51:52 +0200 Subject: [PATCH 09/10] Remove dash --- cookbook/workflow/new_project_git.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/workflow/new_project_git.rst b/cookbook/workflow/new_project_git.rst index d41c50e781f..a6147874d2b 100644 --- a/cookbook/workflow/new_project_git.rst +++ b/cookbook/workflow/new_project_git.rst @@ -47,7 +47,7 @@ git repository: As you might have noticed, not all files that were downloaded by Composer in step 1, have been staged for commit by Git. Certain files and folders, such as the project's dependencies (which are managed by Composer), ``parameters.yml`` (which contains sensitive - information such as database credentials), log- and cache files and dumped assets (which are + information such as database credentials), log and cache files and dumped assets (which are created automatically by your project), should not be committed in Git. To help you prevent committing those files and folders by accident, the Standard Distribution comes with a file called ``.gitignore``, which contains a list of files and folders that Git should From 3f3d88659422c718ec41c158be6a0fa81c728ca2 Mon Sep 17 00:00:00 2001 From: Nic Wortel Date: Mon, 19 May 2014 10:53:25 +0200 Subject: [PATCH 10/10] Update the tip about the global .gitignore --- cookbook/workflow/new_project_git.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/cookbook/workflow/new_project_git.rst b/cookbook/workflow/new_project_git.rst index a6147874d2b..8baf116d60f 100644 --- a/cookbook/workflow/new_project_git.rst +++ b/cookbook/workflow/new_project_git.rst @@ -55,9 +55,9 @@ git repository: .. tip:: - You may also want to create a .gitignore file that can be used system-wide, - in which case, you can find more information here: `Github .gitignore`_ - This way you can exclude files/folders often used by your IDE for all of your projects. + You may also want to create a ``.gitignore`` file that can be used system-wide. + This allows you to exclude files/folders for all your projects that are created by + your IDE or operating system. For details, see `Github .gitignore`_. #. Create an initial commit with your started project: