2018-02-16 23:00:40 +07:00
|
|
|
|
|
|
|
|
.. _odoosh-advanced-submodules:
|
|
|
|
|
|
2023-02-10 23:01:29 +07:00
|
|
|
==========
|
2018-02-16 23:00:40 +07:00
|
|
|
Submodules
|
2023-02-10 23:01:29 +07:00
|
|
|
==========
|
2018-02-16 23:00:40 +07:00
|
|
|
|
|
|
|
|
Overview
|
|
|
|
|
========
|
|
|
|
|
|
|
|
|
|
A `Git submodule <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_ allows you to integrate other Git projects
|
|
|
|
|
into your code, without the need to copy-paste all their code.
|
|
|
|
|
|
|
|
|
|
Indeed, your custom modules can depend on modules from other repositories.
|
|
|
|
|
Regarding Odoo, this feature allows you to add modules from other Git repositories into the branches of your repository.
|
|
|
|
|
Adding these dependencies in your branch through submodules makes the deployment of your code and servers easier,
|
|
|
|
|
as you can clone the repositories added as submodules at the same time you clone your own repository.
|
|
|
|
|
|
|
|
|
|
Besides, you can choose the branch of the repository added as submodule
|
|
|
|
|
and you have the control of the revision you want.
|
2018-03-28 22:32:25 +07:00
|
|
|
It's up to you to decide whether you want to pin the submodule to a specific revision and when you want to update
|
2018-02-16 23:00:40 +07:00
|
|
|
to a newer revision.
|
|
|
|
|
|
2018-04-03 18:27:11 +07:00
|
|
|
In Odoo.sh, the submodules give you the possibility to use and depend on modules available in other repositories.
|
2018-02-16 23:00:40 +07:00
|
|
|
The platform will detect that you added modules through submodules in your branches
|
|
|
|
|
and add them to your addons path automatically so you can install them in your databases.
|
|
|
|
|
|
|
|
|
|
If you add private repositories as submodules in your branches,
|
|
|
|
|
you need to configure a deploy key in your Odoo.sh project settings and in your repository settings.
|
|
|
|
|
Otherwise Odoo.sh won't be allowed to download them.
|
|
|
|
|
The procedure is detailed in the chapter :ref:`Settings > Submodules <odoosh-gettingstarted-settings-submodules>`.
|
|
|
|
|
|
|
|
|
|
Adding a submodule
|
|
|
|
|
==================
|
|
|
|
|
|
|
|
|
|
With Odoo.sh (simple)
|
|
|
|
|
---------------------
|
|
|
|
|
|
2020-05-04 22:14:36 +07:00
|
|
|
.. warning::
|
|
|
|
|
For now it is not possible to add **private** repositories with this method. You can nevertheless
|
|
|
|
|
do so :ref:`with Git <odoosh-advanced-submodules-withgit>`.
|
|
|
|
|
|
2018-02-16 23:00:40 +07:00
|
|
|
On Odoo.sh, in the branches view of your project, choose the branch in which you want to add a submodule.
|
|
|
|
|
|
|
|
|
|
In the upper right corner, click on the *Submodule* button, and then on *Run*.
|
|
|
|
|
|
[MOV] content/*: move resource files into their related page's directory
Since odoo/documentation#903, the guideline for the location of new
resource (images, downloadable files, RST includes...) files is to place
those inside the directory of the RST page that references them.
For example, if `doc1.rst` has a reference to `image.png` and to
`download.zip`, the file structure should look like this:
├── parent_doc/
│ └── doc1/
│ │ └── image.png
│ │ └── download.zip
│ └── doc1.rst
│ └── doc2.rst
├── parent_doc.rst
Before this commit, most of the resource files were still located inside
'media' directories holding all the resource files referenced by RST
pages located at the same level as these directories. In the example
above, a single 'media' directory would hold all the resource files
referenced by both `doc1.rst` and `doc2.rst`. Doing so prevented us from
figuring out easily which resource file was referenced by which RST page
and, thus, lead to unused resource files piling up in the repository. It
also made it more complicated to define codeowners regex rules because a
team could not simply be assigned to `/some_page.*` but needed to be
assigned to both `/some_page\.rst` and to the location of 'media'.
In order to help new content writers figure out the guideline when
taking examples from other RST pages, this commit retroactively applies
the guideline to existing resource files and 'media' directories. The
left-over resource files that are not referenced by any RST page are
removed.
task-2497965
Part-of: odoo/documentation#2068
2022-05-20 16:54:32 +07:00
|
|
|
.. image:: submodules/advanced-submodules-button.png
|
2018-02-16 23:00:40 +07:00
|
|
|
:align: center
|
|
|
|
|
|
|
|
|
|
A dialog with a form is shown. Fill the inputs as follows:
|
|
|
|
|
|
|
|
|
|
* Repository URL: The SSH URL of the repository.
|
|
|
|
|
* Branch: The branch you want to use.
|
|
|
|
|
* Path: The folder in which you want to add this submodule in your branch.
|
|
|
|
|
|
[MOV] content/*: move resource files into their related page's directory
Since odoo/documentation#903, the guideline for the location of new
resource (images, downloadable files, RST includes...) files is to place
those inside the directory of the RST page that references them.
For example, if `doc1.rst` has a reference to `image.png` and to
`download.zip`, the file structure should look like this:
├── parent_doc/
│ └── doc1/
│ │ └── image.png
│ │ └── download.zip
│ └── doc1.rst
│ └── doc2.rst
├── parent_doc.rst
Before this commit, most of the resource files were still located inside
'media' directories holding all the resource files referenced by RST
pages located at the same level as these directories. In the example
above, a single 'media' directory would hold all the resource files
referenced by both `doc1.rst` and `doc2.rst`. Doing so prevented us from
figuring out easily which resource file was referenced by which RST page
and, thus, lead to unused resource files piling up in the repository. It
also made it more complicated to define codeowners regex rules because a
team could not simply be assigned to `/some_page.*` but needed to be
assigned to both `/some_page\.rst` and to the location of 'media'.
In order to help new content writers figure out the guideline when
taking examples from other RST pages, this commit retroactively applies
the guideline to existing resource files and 'media' directories. The
left-over resource files that are not referenced by any RST page are
removed.
task-2497965
Part-of: odoo/documentation#2068
2022-05-20 16:54:32 +07:00
|
|
|
.. image:: submodules/advanced-submodules-dialog.png
|
2018-02-16 23:00:40 +07:00
|
|
|
:align: center
|
|
|
|
|
|
|
|
|
|
On Github, you can get the repository URL with the *Clone or download* button of the repository. Make sure to *use SSH*.
|
|
|
|
|
|
[MOV] content/*: move resource files into their related page's directory
Since odoo/documentation#903, the guideline for the location of new
resource (images, downloadable files, RST includes...) files is to place
those inside the directory of the RST page that references them.
For example, if `doc1.rst` has a reference to `image.png` and to
`download.zip`, the file structure should look like this:
├── parent_doc/
│ └── doc1/
│ │ └── image.png
│ │ └── download.zip
│ └── doc1.rst
│ └── doc2.rst
├── parent_doc.rst
Before this commit, most of the resource files were still located inside
'media' directories holding all the resource files referenced by RST
pages located at the same level as these directories. In the example
above, a single 'media' directory would hold all the resource files
referenced by both `doc1.rst` and `doc2.rst`. Doing so prevented us from
figuring out easily which resource file was referenced by which RST page
and, thus, lead to unused resource files piling up in the repository. It
also made it more complicated to define codeowners regex rules because a
team could not simply be assigned to `/some_page.*` but needed to be
assigned to both `/some_page\.rst` and to the location of 'media'.
In order to help new content writers figure out the guideline when
taking examples from other RST pages, this commit retroactively applies
the guideline to existing resource files and 'media' directories. The
left-over resource files that are not referenced by any RST page are
removed.
task-2497965
Part-of: odoo/documentation#2068
2022-05-20 16:54:32 +07:00
|
|
|
.. image:: submodules/advanced-submodules-github-sshurl.png
|
2018-02-16 23:00:40 +07:00
|
|
|
:align: center
|
|
|
|
|
|
|
|
|
|
.. _odoosh-advanced-submodules-withgit:
|
|
|
|
|
|
|
|
|
|
With Git (advanced)
|
2023-02-10 23:01:29 +07:00
|
|
|
-------------------
|
2018-02-16 23:00:40 +07:00
|
|
|
|
|
|
|
|
In a terminal, in the folder where your Git repository is cloned,
|
|
|
|
|
checkout the branch in which you want to add a submodule:
|
|
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
|
|
$ git checkout <branch>
|
|
|
|
|
|
|
|
|
|
Then, add the submodule using the command below:
|
|
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
|
|
$ git submodule add -b <branch> <git@yourprovider.com>:<username/repository.git> <path>
|
|
|
|
|
|
|
|
|
|
Replace
|
|
|
|
|
|
|
|
|
|
* *<git@yourprovider.com>:<username/repository.git>* by the SSH URL of the repository you want to add as submodule,
|
|
|
|
|
* *<branch>* by the branch you want to use in the above repository,
|
|
|
|
|
* *<path>* by the folder in which you want to add this submodule.
|
|
|
|
|
|
|
|
|
|
Commit and push your changes:
|
|
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
|
|
$ git commit -a && git push -u <remote> <branch>
|
|
|
|
|
|
|
|
|
|
Replace
|
|
|
|
|
|
|
|
|
|
* <remote> by the repository on which you want to push your changes. For a standard Git setup, this is *origin*.
|
|
|
|
|
* <branch> by the branch on which you want to push your changes.
|
|
|
|
|
Most likely the branch you used :code:`git checkout` on in the first step.
|
|
|
|
|
|
|
|
|
|
You can read the `git-scm.com documentation <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_
|
|
|
|
|
for more details about the Git submodules.
|
|
|
|
|
For instance, if you would like to update your submodules to have their latest revision,
|
|
|
|
|
you can follow the chapter
|
2020-07-01 19:25:53 +07:00
|
|
|
`Pulling in Upstream changes <https://git-scm.com/book/en/v2/Git-Tools-Submodules#_pulling_in_upstream_changes_from_the_submodule_remote>`_.
|
2018-09-18 23:15:28 +07:00
|
|
|
|
|
|
|
|
Ignore modules
|
|
|
|
|
==============
|
|
|
|
|
|
|
|
|
|
If you're adding a repository that contains a lot of modules, you may want to ignore some of them in case there are any
|
|
|
|
|
that are installed automatically. To do so, you can prefix your submodule folder with a :code:`.`. The platform will
|
|
|
|
|
ignore this folder and you can hand pick your modules by creating symlinks to them from another folder.
|