GitX

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'.

  • No labels