Skip to content

Commit fb33f52

Browse files
hrbonzhrbonz
committed
copy cookbook/workflow/new_project_git.rst toi use as base for project followed in Subversion
1 parent 006486e commit fb33f52

File tree

1 file changed

+152
-0
lines changed

1 file changed

+152
-0
lines changed

‎cookbook/workflow/new_project_svn.rst

+152
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
How to Create and store a Symfony2 Project in git
2+
=================================================
3+
4+
.. tip::
5+
6+
Though this entry is specifically about git, the same generic principles
7+
will apply if you're storing your project in Subversion.
8+
9+
Once you've read through :doc:`/book/page_creation` and become familiar with
10+
using Symfony, you'll no-doubt be ready to start your own project. In this
11+
cookbook article, you'll learn the best way to start a new Symfony2 project
12+
that's stored using the `git`_ source control management system.
13+
14+
Initial Project Setup
15+
---------------------
16+
17+
To get started, you'll need to download Symfony and initialize your local
18+
git repository:
19+
20+
1. Download the `Symfony2 Standard Edition`_ without vendors.
21+
22+
2. Unzip/untar the distribution. It will create a folder called Symfony with
23+
your new project structure, config files, etc. Rename it to whatever you like.
24+
25+
3. Create a new file called ``.gitignore`` at the root of your new project
26+
(e.g. next to the ``deps`` file) and paste the following into it. Files
27+
matching these patterns will be ignored by git:
28+
29+
.. code-block:: text
30+
31+
/web/bundles/
32+
/app/bootstrap*
33+
/app/cache/*
34+
/app/logs/*
35+
/vendor/
36+
/app/config/parameters.ini
37+
38+
4. Copy ``app/config/parameters.ini`` to ``app/config/parameters.ini.dist``.
39+
The ``parameters.ini`` file is ignored by git (see above) so that machine-specific
40+
settings like database passwords aren't committed. By creating the ``parameters.ini.dist``
41+
file, new developers can quickly clone the project, copy this file to
42+
``parameters.ini``, customize it, and start developing.
43+
44+
5. Initialize your git repository:
45+
46+
.. code-block:: bash
47+
48+
$ git init
49+
50+
6. Add all of the initial files to git:
51+
52+
.. code-block:: bash
53+
54+
$ git add .
55+
56+
7. Create an initial commit with your started project:
57+
58+
.. code-block:: bash
59+
60+
$ git commit -m "Initial commit"
61+
62+
8. Finally, download all of the third-party vendor libraries:
63+
64+
.. code-block:: bash
65+
66+
$ php bin/vendors install
67+
68+
At this point, you have a fully-functional Symfony2 project that's correctly
69+
committed to git. You can immediately begin development, committing the new
70+
changes to your git repository.
71+
72+
You can continue to follow along with the :doc:`/book/page_creation` chapter
73+
to learn more about how to configure and develop inside your application.
74+
75+
.. tip::
76+
77+
The Symfony2 Standard Edition comes with some example functionality. To
78+
remove the sample code, follow the instructions on the `Standard Edition Readme`_.
79+
80+
.. _cookbook-managing-vendor-libraries:
81+
82+
Managing Vendor Libraries with bin/vendors and deps
83+
---------------------------------------------------
84+
85+
Every Symfony project uses a large group of third-party "vendor" libraries.
86+
87+
By default, these libraries are downloaded by running the ``php bin/vendors install``
88+
script. This script reads from the ``deps`` file, and downloads the given
89+
libraries into the ``vendor/`` directory. It also reads ``deps.lock`` file,
90+
pinning each library listed there to the exact git commit hash.
91+
92+
In this setup, the vendors libraries aren't part of your git repository,
93+
not even as submodules. Instead, we rely on the ``deps`` and ``deps.lock``
94+
files and the ``bin/vendors`` script to manage everything. Those files are
95+
part of your repository, so the necessary versions of each third-party library
96+
are version-controlled in git, and you can use the vendors script to bring
97+
your project up to date.
98+
99+
Whenever a developer clones a project, he/she should run the ``php bin/vendors install``
100+
script to ensure that all of the needed vendor libraries are downloaded.
101+
102+
.. sidebar:: Upgrading Symfony
103+
104+
Since Symfony is just a group of third-party libraries and third-party
105+
libraries are entirely controlled through ``deps`` and ``deps.lock``,
106+
upgrading Symfony means simply upgrading each of these files to match
107+
their state in the latest Symfony Standard Edition.
108+
109+
Of course, if you've added new entries to ``deps`` or ``deps.lock``, be sure
110+
to replace only the original parts (i.e. be sure not to also delete any of
111+
your custom entries).
112+
113+
.. caution::
114+
115+
There is also a ``php bin/vendors update`` command, but this has nothing
116+
to do with upgrading your project and you will normally not need to use
117+
it. This command is used to freeze the versions of all of your vendor libraries
118+
by updating them to the version specified in ``deps`` and recording it
119+
into the ``deps.lock`` file.
120+
121+
Vendors and Submodules
122+
~~~~~~~~~~~~~~~~~~~~~~
123+
124+
Instead of using the ``deps``, ``bin/vendors`` system for managing your vendor
125+
libraries, you may instead choose to use native `git submodules`_. There
126+
is nothing wrong with this approach, though the ``deps`` system is the official
127+
way to solve this problem and git submodules can be difficult to work with
128+
at times.
129+
130+
Storing your Project on a Remote Server
131+
---------------------------------------
132+
133+
You now have a fully-functional Symfony2 project stored in git. However,
134+
in most cases, you'll also want to store your project on a remote server
135+
both for backup purposes, and so that other developers can collaborate on
136+
the project.
137+
138+
The easiest way to store your project on a remote server is via `GitHub`_.
139+
Public repositories are free, however you will need to pay a monthly fee
140+
to host private repositories.
141+
142+
Alternatively, you can store your git repository on any server by creating
143+
a `barebones repository`_ and then pushing to it. One library that helps
144+
manage this is `Gitolite`_.
145+
146+
.. _`git`: http://git-scm.com/
147+
.. _`Symfony2 Standard Edition`: http://symfony.com/download
148+
.. _`Standard Edition Readme`: https://github.com/symfony/symfony-standard/blob/master/README.md
149+
.. _`git submodules`: http://book.git-scm.com/5_submodules.html
150+
.. _`GitHub`: https://github.com/
151+
.. _`barebones repository`: http://progit.org/book/ch4-4.html
152+
.. _`Gitolite`: https://github.com/sitaramc/gitolite

0 commit comments

Comments
 (0)