Name
gx add-module - Add an external Git repository as an X-Module to the parent Git repository.
Synopsis
gx add-module [--help] [--no-sync] [--pull-only] [--git-dir=PARENT_REPOS] [--merge-type=MERGE_TYPE] [--ref=PARENT_REF:MODULE_REF] [--squash-rule=SQUASH_RULE] [--subtree=SUBTREE_PATH] [--exclude-path=PATTERN]… MODULE_REPOS MODULE_PATH
Description
Add an external Git repository as an X-Module to the parent Git repository.
This command creates an X-Module - a directory in the parent Git repository, synced with another Git repository. Every 'git push' to the parent repository, that changes files in this directory, will also change the same files in the corresponding external Git repository. Changes, made directly to the external Git repository, will be applied to the X-Module after running gx sync.
This way the X-Module directory becomes bi-directionally synchronized with the external Git repository.
Unidirectional synchronization (only from the external Git repository to the X-Module directory, but not back) is also possible using --pull-only option. See the details below.
The simplest way to start working with X-Modules is to run
$ gx add-module MODULE_URL MODULE_PATH
from the directory of your Git repository. For example:
$ gx add-module http://example.com/repos/mylibrary.git contrib/mylibrary
After that, a 'contrib/mylibrary' directory will be created in the 'master' branch of that Git repository ('parent') and the content of the directory will be the same as that of 'mylibrary.git' repository. To create an X-Module in another branch than 'master', use --ref option.
There are multiple ways to incorporate the history of the X-Module into the parent Git repository, they are controlled by --merge-type and --squash-rule options. See the details below.
By default, gx add-module command fetches the X-Module history and creates the X-Module directory immediately. Yet sometimes one could want to postpone this to create several X-Modules with one commit. To do that, use --no-sync option with every gx add-module invocation and then run
$ gx sync
to apply changes.
To see the list of X-Modules on some branch, use gx status command.
To delete X-Modules, use gx delete-module command.
The gx add-module command also installs a pre-receive hook into the parent repository. With every 'git push' to this repository, the changes in the X-Modules will be sent to the corresponding external repositories. The transfer in the opposite direction is not performed automatically, see gx sync command for details.
Options
- --exclude-path=PATTERN
-
Specify one or several patterns to exclude files from translation.
For example,
--exclude-path *.iso --exclude-path=/build
These patterns are similar to .gitignore rules. If the pattern contains '/' it is considered as non-recursive; otherwise, it’s applied recursively. The special symbols '!', '*' and '**' are supported.
- --git-dir=PARENT_REPOS
-
The path to the parent Git repository, where an X-Module is to be created.
Default: current directory or $GIT_DIR if specified.
- --help
-
Display this help message.
- --merge-type=MERGE_TYPE
-
Valid values: MERGE, REBASE
Default: MERGE
This option defines, how X-Module history is incorporated into the parent repository.
The default value (MERGE) means that the module history will be merged into the parent history.
M1--M2--M3 module history \ P1--P2--P3--X parent history
If some M4 and M5 are added to the module later, gx sync command will merge them into the parent Git repository history using a separate merge commit.
M1--M2--M3--M4--M5 module history \ \ P1--P2--P3--X-------Y parent history
REBASE means that the module history will be added to the top of the parent history.
M1--M2--M3 module history P1--P2--P3--M1--M2--M3 parent history
- --no-sync
-
Do not apply the changes to the parent repository tree and history, just schedule them. To apply the changes, run gx sync command or push to this repository.
This is useful to create several X-Modules with one commit.
- --pull-only
-
One-way synchronization.
When this option is used, the external repository is NOT updated on pushes to the parent repository. Still, the X-Module inside the parent repository is updated with changes from the external repository after running gx sync command.
By default, the synchronization is two-way.
- --ref=PARENT_REF:MODULE_REF
-
References in the parent and external repositories to be synced.
Default:
refs/heads/master:refs/heads/master
These references define branches to be synchronized.
For example, if you want to synchronize the 'production' branch in the external repository with the 'development' branch in the parent repository, the pair will look like this:
refs/heads/development:refs/heads/production
- --squash-rule=SQUASH_RULE
-
Valid values: NEVER, ALWAYS, ONCE
Default: NEVER
This option defines whether and when the commit history of the external repository history will be squashed into one commit in the parent repository.
The default value NEVER means that there’s no squashing.
ALWAYS means that upon gx sync command all new commits from the external repository will be replaced with one commit ('squashed') in the parent repository history.
ONCE means that, only when a module is added to the parent repository, all commits from the history of the external repository are replaced with one commit ('squashed') in the parent repository history. All further commits to the external repository will be copied to the parent repository as they are, without squashing.
- --subtree=SUBTREE_PATH
-
The path to the directory in the external repository to be synced with the X-Module. When no subtree is specified, the whole external repository is synced.
Arguments
- MODULE_REPOS
-
URL or path to the bare Git repository to be synced with an X-Module.
The URL should allow 'git push' and 'git clone' without asking a password.
If the repository requires credentials either:
- they should be specified directly in the URL; OR
- a passwordless login should be set with the SSH access; OR
- the 'credential.helper' feature of Git should be used. For details, see https://git-scm.com/docs/gitcredentials
- MODULE_PATH
-
The path to the directory in the parent repository where an X-Module is to be created.
For example: 'contrib/mylibrary' or 'component'.