Skip to content

Commit

Permalink
Merge 7afa7c8 into 4fdc134
Browse files Browse the repository at this point in the history
  • Loading branch information
@pomek
pomek committed Sep 12, 2018
2 parents 4fdc134 + 7afa7c8 commit b317a8f
Show file tree
Hide file tree
Showing 44 changed files with 3,294 additions and 1,116 deletions.
132 changes: 91 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,9 @@ First, create a configuration file `mgit.json`:

(Keys of the `dependencies` object are package names and values are repository URLs (GitHub identifiers in this case). Read more about the [`dependencies` option](#the-dependencies-option).)

And run `mgit bootstrap` to clone all the repositories. By default, they will be cloned to `<cwd>/packages/` directory:
And run `mgit sync` to clone all the repositories. By default, they will be cloned to `<cwd>/packages/` directory:

```
```bash
packages/
ckeditor5-engine/
mgit/
Expand All @@ -52,23 +52,14 @@ packages/
CLI options:

```
--recursive Whether to install dependencies recursively.
Needs to be used together with --repository-include. Only packages
matching these patterns will be cloned recursively.
Default: false.
--packages Directory to which all repositories will be cloned.
--packages Directory to which all repositories will be cloned or are already installed.
Default: '<cwd>/packages/'
--resolver-path Path to a custom repository resolver function.
Default: '@mgit2/lib/default-resolver.js'.
--resolver-url-template Template used to generate repository URL out of a
simplified 'organization/repository' format of the dependencies option.
Default: 'git@github.com:${ path }.git'.
--resolver-directory-name Defines how the target directory (where the repository will be cloned)
Expand All @@ -80,31 +71,24 @@ CLI options:
This option can be useful when scoped npm packages are used and one wants to decide
whether the repository will be cloned to packages/@scope/pkgname' or 'packages/pkgname'.
Default: 'git'
--resolver-default-branch The branch name to use if not specified in mgit.json dependencies.
Default: 'master'
--ignore Ignores packages which names match the given glob pattern.
For example:
> mgit exec --ignore="foo*" "git st"
--ignore Ignores packages which names match the given glob pattern. E.g.:
> mgit exec --ignore="foo*" "git st"
Will ignore all packages which names start from "foo".
Default: null
--scope Restricts the command to packages which names match the given glob pattern.
Default: null
```

All these options can also be specified in `mgit.json` (options passed through CLI takes precedence):

```js
```json
{
"packages": "/workspace/modules",
"resolverDirectoryName": "npm",
Expand Down Expand Up @@ -146,6 +130,8 @@ Examples:

### Recursive cloning

**Note**: `--recursive` option is a commands option, so remember about [`--`](https://unix.stackexchange.com/questions/147143/when-and-how-was-the-double-dash-introduced-as-an-end-of-options-delimiter) in order to separate options for mgit and specified command.

When the `--recursive` option is used mgit will clone repositories recursively. First, it will clone the `dependencies` specified in `mgit.json` and, then, their `dependencies` and `devDependencies` specified in `package.json` files located in cloned repositories.

However, mgit needs to know repository URLs of those dependencies, as well as which dependencies to clone (usually, only the ones maintained by you). In order to configure that you need to use a custom repository resolver (`--resolver-path`).
Expand All @@ -163,13 +149,13 @@ const parseRepositoryUrl = require( 'mgit2/lib/utils/parserepositoryurl' );
* Resolves repository URL for a given package name.
*
* @param {String} packageName Package name.
* @param {Options} data.options The options object.
* @param {Options} options The options object.
* @returns {Repository|null}
*/
module.exports = function resolver( packageName, options ) {
// If package name starts with '@ckeditor/ckeditor5-*' clone it from 'ckeditor/ckeditor5-*'.
if ( packageName.startsWith( '@ckeditor/ckeditor5-' ) ) {
repositoryUrl = packageName.slice( 1 );
const repositoryUrl = packageName.slice( 1 );

return parseRepositoryUrl( repositoryUrl );
}
Expand All @@ -185,49 +171,74 @@ You can also check the [default resolver](https://github.com/cksource/mgit2/blob

CI servers, such as Travis, can't clone repositories using Git URLs (such as `git@github.com:cksource/mgit.git`). By default, mgit uses Git URLs because it assumes that you'll want to commit to these repositories (and don't want to be asked for a password every time).

If you need to run mgit on a CI server, then configure it to use HTTP URLs:
If you need to run mgit on a CI server, then configure it to use HTTPS URLs:

```bash
mgit --resolver-url-template="https://github.com/\${ path }.git"
```

You can also use full HTTPs URLs to configure `dependencies` in your `mgit.json`.
You can also use full HTTPS URLs to configure `dependencies` in your `mgit.json`.

## Commands

```bash
$ mgit [command]
```
mgit [command]

For displaying help screen for specified command, type:

```bash
$ mgit [command] --help
```

### bootstrap
### sync

Installs missing packages (i.e. clone them) and check them out to correct branches.
Updates dependencies. Switches repositories to correct branches (specified in `mgit.json`) and pulls changes.

This command will not change existing repositories, so you can always safely use it. It's useful to bootstrap the project initially, but later you'll rather want to use `mgit update`.
If any dependency is missing, the command will install this dependency as well.

Example:
This command does not touch repositories in which there are uncommitted changes.

Examples:

```bash
mgit bootstrap --recursive --resolver=path ./dev/custom-repository-resolver.js
mgit sync -- --recursive
```

### update
### pull

Updates dependencies. Switches repositories to correct branches (specified in `mgit.json`) and pulls changes.
Pulls changes in existing repositories. It does not change branches in the repositories and pull the changes even if
the repository contains uncommitted changes.

If any dependency is missing, the command will install it too.
Examples:

This command does not touch repositories in which there are uncommitted changes.
```bash
mgit pull -- --recursive
```

### push

Pushes changes in existing repositories.

Examples:

```bash
mgit push
```

### fetch

Fetches changes in existing repositories.

Examples:

```bash
mgit update --recursive
mgit fetch
```

### exec

For every cloned repository executes the specified shell command.
Executes specified shell command in existing repositories.

Example:

Expand All @@ -246,14 +257,53 @@ mgit exec 'echo `pwd`'
# /home/mgit/packages/organization/repository-2
```

### save-hashes
### commit (alias: `ci`)

For every repository that contains changes which can be committed, makes a commit with these files.
You need to specify the message for the commit.

Example:

```bash
mgit commit -- --message 'Introduce PULL_REQUEST_TEMPLATE.md.'

# Executes `git commit --message 'Introduce PULL_REQUEST_TEMPLATE.md.'` command on each repository.
# Commit will be made in repositories that "git status" returns a list if changed files (these files must be tracked by Git).
```

### close

Requires a second argument which is a branch name that will be merged to current one. You can also specify the message
which will be added to the default git-merge message.

Repositories which do not have specified branch will be ignored.

After merging, the merged branch will be removed from the remote.

Example:

```bash
# Assumptions: we are on "master" branch and "develop" branch exists.
mgit merge develop -- --message 'These changes are required for the future release.'

# Branch "develop" will be merged into "master".
# Branch "develop" will be removed from the origin.
```

### save

Saves hashes of packages in `mgit.json`. It allows to easily fix project to a specific state.

Example:

```bash
mgit save-hashes
mgit save
```

If you would like to save name of branches instead of current commit, you can use an option `--branch`:

```bash
mgit save -- --branch
```

### status (alias: `st`)
Expand Down Expand Up @@ -311,7 +361,7 @@ mgit diff -- master...HEAD

### checkout (alias: `co`)

Changes branches in repositories according to the configuration file. It does not pull the changes and hance is much faster than `mgit update`. The command is useful for bisecting if your main repository contain a revision log like CKEditor 5's [`master-revision`](https://github.com/ckeditor/ckeditor5/commits/master-revisions) branch.
Changes branches in repositories according to the configuration file. It does not pull the changes and hance is much faster than `mgit sync`. The command is useful for bisecting if your main repository contain a revision log like CKEditor 5's [`master-revision`](https://github.com/ckeditor/ckeditor5/commits/master-revisions) branch.

```bash
mgit checkout
Expand Down
Loading

0 comments on commit b317a8f

Please sign in to comment.