From f26fe66751145ca56c849007491d838353301c1a Mon Sep 17 00:00:00 2001 From: Antoine Durieux Date: Wed, 29 Feb 2012 10:14:53 +0100 Subject: [PATCH 1/9] Details about the deps file. --- ...endor_deps.rst.inc => vendor_deps.rst.inc} | 46 ++++++++++++++++++- 1 file changed, 44 insertions(+), 2 deletions(-) rename cookbook/workflow/{_vendor_deps.rst.inc => vendor_deps.rst.inc} (60%) diff --git a/cookbook/workflow/_vendor_deps.rst.inc b/cookbook/workflow/vendor_deps.rst.inc similarity index 60% rename from cookbook/workflow/_vendor_deps.rst.inc rename to cookbook/workflow/vendor_deps.rst.inc index d36d14d7d26..26581480c5c 100644 --- a/cookbook/workflow/_vendor_deps.rst.inc +++ b/cookbook/workflow/vendor_deps.rst.inc @@ -1,5 +1,8 @@ Managing Vendor Libraries with bin/vendors and deps ---------------------------------------------------- +=================================================== + +How does it work ? +------------------ Every Symfony project uses a group of third-party "vendor" libraries. One way or another the goal is to download these files into your ``vendor/`` @@ -46,4 +49,43 @@ script to ensure that all of the needed vendor libraries are downloaded. to do with upgrading your project and you will normally not need to use it. This command is used to freeze the versions of all of your vendor libraries by updating them to the version specified in ``deps`` and recording it - into the ``deps.lock`` file. \ No newline at end of file + into the ``deps.lock`` file. + + +Hacking vendor libraries +------------------------ + +Sometimes, you want a specific branch, tag, or commit of a library to be downloaded +or upgraded. You can set that directly to the ``deps`` file : + +.. code-block:: text + + [AcmeAwesomeBundle] + git=http://github.com/johndoe/Acme/AwesomeBundle.git + target=/bundles/Acme/AwesomeBundle + version=the-awesome-version + +* The ``git`` option sets the URL of the library. It can use various protocols, like +``http://`` as well as ``git://``. +* The ``target`` option specifies where the repository will live : plain Symfony +bundles should go under the ``vendor/bundles/Acme`` directory, other third-party +libraries usually go to ``vendor/my-awesome-libreary-name``. The target directory +defaults to this last option when not specified. +* The ``version`` option allows you to set a specific revision. You can use a tag +(``version=origin/0.42``) or a branch name (``refs/remotes/origin/awesome-branch``). +It defaults to ``origin/HEAD``. + + +Updating workflow +----------------- + +When you execute the ``php bin/vendors install``, for every library, the script +first checks if the install directory exists. + +If it does not (and ONLY if it does not, it runs a ``git clone``. + +Then, it does a ``git fetch origin`` and a ``git reset --hard the-awesome-version``. + +This means that the repository will only be cloned once. If you want to perform +any change of the git remote, you MUST delete the entire target directory, not +only its content. \ No newline at end of file From d031631fd9ecea74c9bf4590d05ef0f6cd184da6 Mon Sep 17 00:00:00 2001 From: Antoine Durieux Date: Wed, 29 Feb 2012 10:25:20 +0100 Subject: [PATCH 2/9] Renamed file. --- cookbook/workflow/{vendor_deps.rst.inc => vendor_deps.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename cookbook/workflow/{vendor_deps.rst.inc => vendor_deps.rst} (100%) diff --git a/cookbook/workflow/vendor_deps.rst.inc b/cookbook/workflow/vendor_deps.rst similarity index 100% rename from cookbook/workflow/vendor_deps.rst.inc rename to cookbook/workflow/vendor_deps.rst From 847165cc5f7eb50717b6d560efabca391dc4f4ac Mon Sep 17 00:00:00 2001 From: Antoine DURIEUX Date: Wed, 29 Feb 2012 10:27:44 +0100 Subject: [PATCH 3/9] Cleaned up formatting. --- cookbook/workflow/vendor_deps.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/cookbook/workflow/vendor_deps.rst b/cookbook/workflow/vendor_deps.rst index 26581480c5c..86a95799455 100644 --- a/cookbook/workflow/vendor_deps.rst +++ b/cookbook/workflow/vendor_deps.rst @@ -64,13 +64,16 @@ or upgraded. You can set that directly to the ``deps`` file : git=http://github.com/johndoe/Acme/AwesomeBundle.git target=/bundles/Acme/AwesomeBundle version=the-awesome-version - + + * The ``git`` option sets the URL of the library. It can use various protocols, like ``http://`` as well as ``git://``. + * The ``target`` option specifies where the repository will live : plain Symfony bundles should go under the ``vendor/bundles/Acme`` directory, other third-party libraries usually go to ``vendor/my-awesome-libreary-name``. The target directory defaults to this last option when not specified. + * The ``version`` option allows you to set a specific revision. You can use a tag (``version=origin/0.42``) or a branch name (``refs/remotes/origin/awesome-branch``). It defaults to ``origin/HEAD``. From 6230ba5e0c0aa8036f44eb20cd14a9e53bb18f1b Mon Sep 17 00:00:00 2001 From: Antoine DURIEUX Date: Wed, 29 Feb 2012 10:28:56 +0100 Subject: [PATCH 4/9] Spaces. --- cookbook/workflow/vendor_deps.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cookbook/workflow/vendor_deps.rst b/cookbook/workflow/vendor_deps.rst index 86a95799455..2aaae857ccd 100644 --- a/cookbook/workflow/vendor_deps.rst +++ b/cookbook/workflow/vendor_deps.rst @@ -66,16 +66,16 @@ or upgraded. You can set that directly to the ``deps`` file : version=the-awesome-version -* The ``git`` option sets the URL of the library. It can use various protocols, like -``http://`` as well as ``git://``. +* The ``git`` option sets the URL of the library. It can use various protocols, +like ``http://`` as well as ``git://``. * The ``target`` option specifies where the repository will live : plain Symfony -bundles should go under the ``vendor/bundles/Acme`` directory, other third-party +bundles should go under the ``vendor/bundles/Acme`` directory, other third-party libraries usually go to ``vendor/my-awesome-libreary-name``. The target directory defaults to this last option when not specified. * The ``version`` option allows you to set a specific revision. You can use a tag -(``version=origin/0.42``) or a branch name (``refs/remotes/origin/awesome-branch``). +(``version=origin/0.42``) or a branch name (``refs/remotes/origin/awesome-branch``). It defaults to ``origin/HEAD``. From 6a6292186c05225e575fb01ac59a460766b4c7fa Mon Sep 17 00:00:00 2001 From: Antoine DURIEUX Date: Wed, 29 Feb 2012 10:29:40 +0100 Subject: [PATCH 5/9] More spaces... --- cookbook/workflow/vendor_deps.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/cookbook/workflow/vendor_deps.rst b/cookbook/workflow/vendor_deps.rst index 2aaae857ccd..fb448671094 100644 --- a/cookbook/workflow/vendor_deps.rst +++ b/cookbook/workflow/vendor_deps.rst @@ -66,23 +66,23 @@ or upgraded. You can set that directly to the ``deps`` file : version=the-awesome-version -* The ``git`` option sets the URL of the library. It can use various protocols, +* The ``git`` option sets the URL of the library. It can use various protocols, like ``http://`` as well as ``git://``. -* The ``target`` option specifies where the repository will live : plain Symfony -bundles should go under the ``vendor/bundles/Acme`` directory, other third-party -libraries usually go to ``vendor/my-awesome-libreary-name``. The target directory -defaults to this last option when not specified. +* The ``target`` option specifies where the repository will live : plain Symfony +bundles should go under the ``vendor/bundles/Acme`` directory, other third-party +libraries usually go to ``vendor/my-awesome-libreary-name``. The target directory +defaults to this last option when not specified. -* The ``version`` option allows you to set a specific revision. You can use a tag -(``version=origin/0.42``) or a branch name (``refs/remotes/origin/awesome-branch``). +* The ``version`` option allows you to set a specific revision. You can use a tag +(``version=origin/0.42``) or a branch name (``refs/remotes/origin/awesome-branch``). It defaults to ``origin/HEAD``. Updating workflow ----------------- -When you execute the ``php bin/vendors install``, for every library, the script +When you execute the ``php bin/vendors install``, for every library, the script first checks if the install directory exists. If it does not (and ONLY if it does not, it runs a ``git clone``. @@ -90,5 +90,5 @@ If it does not (and ONLY if it does not, it runs a ``git clone``. Then, it does a ``git fetch origin`` and a ``git reset --hard the-awesome-version``. This means that the repository will only be cloned once. If you want to perform -any change of the git remote, you MUST delete the entire target directory, not +any change of the git remote, you MUST delete the entire target directory, not only its content. \ No newline at end of file From 8ee54416bcab2dd9c37a39015a00adaed32214f0 Mon Sep 17 00:00:00 2001 From: Antoine DURIEUX Date: Wed, 29 Feb 2012 10:30:23 +0100 Subject: [PATCH 6/9] Even more spaces... --- cookbook/workflow/vendor_deps.rst | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) diff --git a/cookbook/workflow/vendor_deps.rst b/cookbook/workflow/vendor_deps.rst index fb448671094..7c454bfc34a 100644 --- a/cookbook/workflow/vendor_deps.rst +++ b/cookbook/workflow/vendor_deps.rst @@ -66,29 +66,20 @@ or upgraded. You can set that directly to the ``deps`` file : version=the-awesome-version -* The ``git`` option sets the URL of the library. It can use various protocols, -like ``http://`` as well as ``git://``. +* The ``git`` option sets the URL of the library. It can use various protocols, like ``http://`` as well as ``git://``. -* The ``target`` option specifies where the repository will live : plain Symfony -bundles should go under the ``vendor/bundles/Acme`` directory, other third-party -libraries usually go to ``vendor/my-awesome-libreary-name``. The target directory -defaults to this last option when not specified. +* The ``target`` option specifies where the repository will live : plain Symfony bundles should go under the ``vendor/bundles/Acme`` directory, other third-party libraries usually go to ``vendor/my-awesome-libreary-name``. The target directory defaults to this last option when not specified. -* The ``version`` option allows you to set a specific revision. You can use a tag -(``version=origin/0.42``) or a branch name (``refs/remotes/origin/awesome-branch``). -It defaults to ``origin/HEAD``. +* The ``version`` option allows you to set a specific revision. You can use a tag (``version=origin/0.42``) or a branch name (``refs/remotes/origin/awesome-branch``). It defaults to ``origin/HEAD``. Updating workflow ----------------- -When you execute the ``php bin/vendors install``, for every library, the script -first checks if the install directory exists. +When you execute the ``php bin/vendors install``, for every library, the script first checks if the install directory exists. If it does not (and ONLY if it does not, it runs a ``git clone``. Then, it does a ``git fetch origin`` and a ``git reset --hard the-awesome-version``. -This means that the repository will only be cloned once. If you want to perform -any change of the git remote, you MUST delete the entire target directory, not -only its content. \ No newline at end of file +This means that the repository will only be cloned once. If you want to perform any change of the git remote, you MUST delete the entire target directory, not only its content. \ No newline at end of file From d3f7fb0c775ad23a3a866b00af34e58c721f566b Mon Sep 17 00:00:00 2001 From: Antoine Durieux Date: Wed, 29 Feb 2012 13:46:07 +0100 Subject: [PATCH 7/9] Typo. --- cookbook/workflow/vendor_deps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/workflow/vendor_deps.rst b/cookbook/workflow/vendor_deps.rst index 7c454bfc34a..230c8311ca9 100644 --- a/cookbook/workflow/vendor_deps.rst +++ b/cookbook/workflow/vendor_deps.rst @@ -68,7 +68,7 @@ or upgraded. You can set that directly to the ``deps`` file : * The ``git`` option sets the URL of the library. It can use various protocols, like ``http://`` as well as ``git://``. -* The ``target`` option specifies where the repository will live : plain Symfony bundles should go under the ``vendor/bundles/Acme`` directory, other third-party libraries usually go to ``vendor/my-awesome-libreary-name``. The target directory defaults to this last option when not specified. +* The ``target`` option specifies where the repository will live : plain Symfony bundles should go under the ``vendor/bundles/Acme`` directory, other third-party libraries usually go to ``vendor/my-awesome-library-name``. The target directory defaults to this last option when not specified. * The ``version`` option allows you to set a specific revision. You can use a tag (``version=origin/0.42``) or a branch name (``refs/remotes/origin/awesome-branch``). It defaults to ``origin/HEAD``. From 71ec9b0815fec35f885d112533069bbc35d8c39e Mon Sep 17 00:00:00 2001 From: Antoine Durieux Date: Wed, 29 Feb 2012 14:00:46 +0100 Subject: [PATCH 8/9] Renamed file. --- cookbook/workflow/{vendor_deps.rst => _vendor_deps.rst.inc} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename cookbook/workflow/{vendor_deps.rst => _vendor_deps.rst.inc} (100%) diff --git a/cookbook/workflow/vendor_deps.rst b/cookbook/workflow/_vendor_deps.rst.inc similarity index 100% rename from cookbook/workflow/vendor_deps.rst rename to cookbook/workflow/_vendor_deps.rst.inc From c7e8cc7b8281cc176c83cfdde24b5353fa9cd888 Mon Sep 17 00:00:00 2001 From: Antoine Durieux Date: Wed, 29 Feb 2012 14:50:46 +0100 Subject: [PATCH 9/9] Changed levels. --- cookbook/workflow/_vendor_deps.rst.inc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/cookbook/workflow/_vendor_deps.rst.inc b/cookbook/workflow/_vendor_deps.rst.inc index 230c8311ca9..8a52a004816 100644 --- a/cookbook/workflow/_vendor_deps.rst.inc +++ b/cookbook/workflow/_vendor_deps.rst.inc @@ -1,8 +1,8 @@ Managing Vendor Libraries with bin/vendors and deps -=================================================== +--------------------------------------------------- + +### How does it work ? -How does it work ? ------------------- Every Symfony project uses a group of third-party "vendor" libraries. One way or another the goal is to download these files into your ``vendor/`` @@ -52,8 +52,8 @@ script to ensure that all of the needed vendor libraries are downloaded. into the ``deps.lock`` file. -Hacking vendor libraries ------------------------- +### Hacking vendor libraries + Sometimes, you want a specific branch, tag, or commit of a library to be downloaded or upgraded. You can set that directly to the ``deps`` file : @@ -73,8 +73,8 @@ or upgraded. You can set that directly to the ``deps`` file : * The ``version`` option allows you to set a specific revision. You can use a tag (``version=origin/0.42``) or a branch name (``refs/remotes/origin/awesome-branch``). It defaults to ``origin/HEAD``. -Updating workflow ------------------ +### Updating workflow + When you execute the ``php bin/vendors install``, for every library, the script first checks if the install directory exists.