Skip to content

Commit

Permalink
Merge a6e508b into 4591908
Browse files Browse the repository at this point in the history
  • Loading branch information
@pomek
pomek committed Jun 17, 2019
2 parents 4591908 + a6e508b commit a4e4ffc
Show file tree
Hide file tree
Showing 35 changed files with 331 additions and 334 deletions.
124 changes: 61 additions & 63 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,50 +1,48 @@
# mgit2
# Mr. Git

<a href="https://www.npmjs.com/package/mgit2"><img src="https://img.shields.io/npm/v/mgit2.svg" alt="mgit2 npm package badge"></a>
<a href="https://travis-ci.org/cksource/mgit2"><img src="https://img.shields.io/travis/cksource/mgit2/master.svg" alt="build status badge"></a>
<a href="https://coveralls.io/github/cksource/mgit2?branch=master"><img src="https://coveralls.io/repos/github/cksource/mgit2/badge.svg?branch=master" alt="Coverage Status"></a>
<a href="https://david-dm.org/cksource/mgit2"><img src="https://img.shields.io/david/cksource/mgit2.svg" alt="mgit2 dependencies status badge"></a>
<a href="https://david-dm.org/cksource/mgit2?type=dev"><img src="https://img.shields.io/david/dev/cksource/mgit2.svg" alt="mgit2 devDependencies status badge"></a>
<a href="https://www.npmjs.com/package/mrgit"><img src="https://img.shields.io/npm/v/mrgit.svg" alt="mrgit npm package badge"></a>
<a href="https://travis-ci.org/cksource/mrgit"><img src="https://img.shields.io/travis/cksource/mrgit/master.svg" alt="build status badge"></a>
<a href="https://coveralls.io/github/cksource/mrgit?branch=master"><img src="https://coveralls.io/repos/github/cksource/mrgit/badge.svg?branch=master" alt="Coverage Status"></a>
<a href="https://david-dm.org/cksource/mrgit"><img src="https://img.shields.io/david/cksource/mrgit.svg" alt="mrgit dependencies status badge"></a>
<a href="https://david-dm.org/cksource/mrgit?type=dev"><img src="https://img.shields.io/david/dev/cksource/mrgit.svg" alt="mrgit devDependencies status badge"></a>

Multi-repo manager for git. A tool for managing projects build using multiple repositories.

mgit2 is designed to work with [yarn workspaces](https://yarnpkg.com/lang/en/docs/workspaces/) and [Lerna](https://github.com/lerna/lerna) out of the box, hence, it mixes the "package" and "repository" concepts. In other words, every repository is meant to be a single [npm](https://npmjs.com) package. It doesn't mean that you must use it with Lerna and npm, but don't be surprised that mgit2 talks about "packages" and works best with npm packages.
`mrgit` is designed to work with [yarn workspaces](https://yarnpkg.com/lang/en/docs/workspaces/) and [Lerna](https://github.com/lerna/lerna) out of the box, hence, it mixes the "package" and "repository" concepts. In other words, every repository is meant to be a single [npm](https://npmjs.com) package. It doesn't mean that you must use it with Lerna and npm, but don't be surprised that mrgit talks about "packages" and works best with npm packages.

## Installation

```bash
npm install -g mgit2
npm install -g mrgit
```

Use:

```bash
mgit --help
mrgit --help
```

**Note:** The command is called `mgit`.

## Usage

First, create a configuration file `mgit.json`:
First, create a configuration file `mrgit.json`:

```json
{
"dependencies": {
"@ckeditor/ckeditor5-engine": "ckeditor/ckeditor5-engine",
"mgit2": "cksource/mgit2"
"mrgit": "cksource/mrgit"
}
}
```

(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 sync` to clone all the repositories. By default, they will be cloned to `<cwd>/packages/` directory:
And run `mrgit sync` to clone all the repositories. By default, they will be cloned to `<cwd>/packages/` directory:

```bash
packages/
ckeditor5-engine/
mgit2/
mrgit/
```

## Configuration
Expand All @@ -58,7 +56,7 @@ CLI options:
--hash Whether to save current commit hashes. Used only by "save" command.
--ignore Ignores packages which names match the given glob pattern. E.g.:
> mgit exec --ignore="foo*" "git status"
> mrgit exec --ignore="foo*" "git status"
Will ignore all packages which names start from "foo".
Default: null
Expand All @@ -72,7 +70,7 @@ CLI options:
--recursive Whether to install dependencies recursively. Used only by "sync" command.
--resolver-path Path to a custom repository resolver function.
Default: '@mgit2/lib/default-resolver.js'
Default: '@mrgit/lib/default-resolver.js'
--resolver-url-template Template used to generate repository URL out of a
simplified 'organization/repository' format of the dependencies option.
Expand All @@ -89,14 +87,14 @@ CLI options:
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.
--resolver-default-branch The branch name to use if not specified in mrgit.json dependencies.
Default: master
--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):
All these options can also be specified in `mrgit.json` (options passed through CLI takes precedence):

```json
{
Expand All @@ -111,9 +109,9 @@ All these options can also be specified in `mgit.json` (options passed through C

### The `dependencies` option

This option specifies repositories which mgit is supposed to clone. It can also clone its dependencies recursively (see [Recursive cloning](#recursive-cloning)).
This option specifies repositories which `mrgit` is supposed to clone. It can also clone its dependencies recursively (see [Recursive cloning](#recursive-cloning)).

The dependency keys can be any strings, but it's recommended to use package names (e.g. npm package names, just like in `package.json`). The values are repository URLs which mgit will clone.
The dependency keys can be any strings, but it's recommended to use package names (e.g. npm package names, just like in `package.json`). The values are repository URLs which `mrgit` will clone.

Examples:

Expand All @@ -140,9 +138,9 @@ Examples:

### Recursive cloning

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.
When the `--recursive` option is used `mrgit` will clone repositories recursively. First, it will clone the `dependencies` specified in `mrgit.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`).
However, `mrgit` 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`).

Resolver is a simple Node.js module which exports the resolver function.

Expand All @@ -151,7 +149,7 @@ For example, assuming that you want to clone all `@ckeditor/ckeditor5-*` package
```js
'use strict';

const parseRepositoryUrl = require( 'mgit2/lib/utils/parserepositoryurl' );
const parseRepositoryUrl = require( 'mrgit/lib/utils/parserepositoryurl' );

/**
* Resolves repository URL for a given package name.
Expand All @@ -173,47 +171,47 @@ module.exports = function resolver( packageName, options ) {
};
```

You can also check the [default resolver](https://github.com/cksource/mgit2/blob/master/lib/default-resolver.js) used by mgit and [the config object definition](https://github.com/cksource/mgit2/blob/master/lib/utils/getconfig.js).
You can also check the [default resolver](https://github.com/cksource/mrgit/blob/master/lib/default-resolver.js) used by `mrgit` and [the config object definition](https://github.com/cksource/mrgit/blob/master/lib/utils/getconfig.js).

### Cloning repositories on CI servers

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).
CI servers, such as Travis, can't clone repositories using Git URLs (such as `git@github.com:cksource/mrgit.git`). By default, `mrgit` 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 HTTPS URLs:
If you need to run `mrgit` on a CI server, then configure it to use HTTPS URLs:

```bash
mgit --resolver-url-template="https://github.com/\${ path }.git"
mrgit --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 `mrgit.json`.

## Commands

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

For displaying help screen for specified command, type:

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

### sync

Updates dependencies. Switches repositories to correct branches (specified in `mgit.json`) and pulls changes.
Updates dependencies. Switches repositories to correct branches (specified in `mrgit.json`) and pulls changes.

If any dependency is missing, the command will install this dependency as well.

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

If in the packages directory will be located some directories that are not specified in `mgit.json`, paths to these directories
If in the packages directory will be located some directories that are not specified in `mrgit.json`, paths to these directories
will be printed out on the screen.

Examples:

```bash
mgit sync --recursive
mrgit sync --recursive
```

### pull
Expand All @@ -224,7 +222,7 @@ the repository contains uncommitted changes.
Examples:

```bash
mgit pull
mrgit pull
```

### push
Expand All @@ -234,7 +232,7 @@ Pushes changes in existing repositories.
Examples:

```bash
mgit push
mrgit push
```

### fetch
Expand All @@ -244,7 +242,7 @@ Fetches changes in existing repositories.
Examples:

```bash
mgit fetch
mrgit fetch
```

### exec
Expand All @@ -254,18 +252,18 @@ Executes specified shell command in existing repositories.
Example:

```bash
mgit exec 'git status'
mrgit exec 'git status'

# Executes `git status` command on each repository.
```

During the task execution, `cwd` is set to the repository path:

```bash
mgit exec 'echo `pwd`'
mrgit exec 'echo `pwd`'

# /home/mgit/packages/organization/repository-1
# /home/mgit/packages/organization/repository-2
# /home/mrgit/packages/organization/repository-1
# /home/mrgit/packages/organization/repository-2
```

### commit (alias: `ci`)
Expand All @@ -276,7 +274,7 @@ You need to specify the message for the commit.
Example:

```bash
mgit commit --message 'Introduce PULL_REQUEST_TEMPLATE.md.'
mrgit 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).
Expand All @@ -295,26 +293,26 @@ Example:

```bash
# Assumptions: we are on "master" branch and "develop" branch exists.
mgit merge develop --message 'These changes are required for the future release.'
mrgit 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.
Saves hashes of packages in `mrgit.json`. It allows to easily fix project to a specific state.

Example:

```bash
mgit save
mrgit save
```

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

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

### status (alias: `st`)
Expand All @@ -324,15 +322,15 @@ Prints a table which contains useful information about the status of repositorie
Example:

```bash
mgit status
mrgit status
# or
mgit st
mrgit st
```

In order to save space in your terminal, you can define the `packagesPrefix` option in your configuration file.
The prefix will be removed from packages' names. Full names of packages aren't needed so we can cut the names.

![An example response of `mgit status` command.](https://user-images.githubusercontent.com/2270764/28871104-5915289e-7783-11e7-8d06-9eac6d7d96ab.png)
![An example response of `mrgit status` command.](https://user-images.githubusercontent.com/2270764/28871104-5915289e-7783-11e7-8d06-9eac6d7d96ab.png)

### diff

Expand All @@ -347,55 +345,55 @@ These options must be separated by a double dash `--`, the same way as [`npm scr
Prints changes from all repositories:

```bash
mgit diff
mrgit diff
```

Prints diffstat from all repositories:

```bash
mgit diff -- --stat
mrgit diff -- --stat
```

Prints staged changes from restricted scope:

```bash
mgit diff --scope=*@(engine|typing)* -- --staged
mrgit diff --scope=*@(engine|typing)* -- --staged
```

Prints changes from repositories which are not on `master`:

```bash
mgit diff -- master...HEAD
mrgit diff -- master...HEAD
```

![An example response of `mgit diff` command.](https://user-images.githubusercontent.com/2270764/28918716-c6f90002-784a-11e7-95ae-8d08c47c5427.png)
![An example response of `mrgit diff` command.](https://user-images.githubusercontent.com/2270764/28918716-c6f90002-784a-11e7-95ae-8d08c47c5427.png)

### 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 sync`.
Changes branches in repositories according to the configuration file. It does not pull the changes and hance is much faster than `mrgit 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
mrgit checkout
# or
mgit co
mrgit co
```

If specified an argument, specified branch will be used instead of default or saved in `mgit.json` file.
If specified an argument, specified branch will be used instead of default or saved in `mrgit.json` file.

```bash
# Checkout all repositories to "stable" branch.
mgit checkout stable
mrgit checkout stable
```

Also you can specify the `--branch` option which means that mgit creates a new branches in repositories that contains changes (that could be committed).
It works on the same terms like `mgit commit`.
Also you can specify the `--branch` option which means that `mrgit` creates a new branches in repositories that contains changes (that could be committed).
It works on the same terms like `mrgit commit`.

```bash
# Create the branch "t/foo" in repositories where "git status" returns a list if changed files (these files must be tracked by Git).
mgit checkout --branch t/foo
mrgit checkout --branch t/foo
```

## Projects using mgit2
## Projects using mrgit

* [CKEditor 5](https://github.com/ckeditor/ckeditor5)
Loading

0 comments on commit a4e4ffc

Please sign in to comment.