Update readme

This commit is contained in:
dece 2020-12-07 00:09:38 +01:00
parent ea2e4574b7
commit 5484a2742f

View file

@ -1,5 +1,79 @@
Mira
====
Small utility to help with Git repository mirroring, using a single JSON config
file. It is standalone and can be easily integrated in cron or systemd.
Small standalone utility to help with Git repository mirroring, using a single
JSON config file. If you read this on Github, I did not push it there myself,
Mira did!
About
-----
Mira automates mirroring a bunch of repository. Some people do not wish to use
Github, Gitlab Cloud or Bitbucket as their primary repository for various
reasons and run their own private Git servers, but making your code available
on these platforms still has advantages (visibility, issues, PR, etc).
Mira is a quick fix to that, hopefully just copy an example below, put it in a
Systemd service and be done with it.
Usage
-----
Example configuration for the mirroring of this repository from a Gitea
instance to its Github mirror:
```json
{
"workspace": "/tmp/mira",
"configurations": [
{
"name": "Gitea to Github",
"mirrors": [
{
"name": "Mira",
"src": "ssh://git@gitea.example.com:12345/Dece/Mira.git",
"dest": "git@github.com:Dece/Mira.git"
}
]
}
]
}
```
The different values are:
- `workspace`: a place where Mira can clone, fetch and push from.
- `configurations`: a set of configurations using similar auth mechanisms.
For now it is quite useless as no such mechanisms are supported.
- `configurations.N.name`: name of a configuration, a directory in the workspace.
- `configurations.N.mirrors`: list of mirrors.
- `mirrors.N.name`: name of a mirror, used to determine the directory where to
clone and work from.
- `mirrors.N.src`: clone and fetch URL for the mirror, passed to `git clone`.
Usually copying the URL provided by your server for cloning should suffice
(HTTP or SSH).
- `mirrors.N.dest`: push URL for the mirror, set as a remote named "mirror".
It may require some testing to determine what are the appropriate URLs for
clone and push. Gitea with SSH uses the full "ssh://" syntax, whereas Github
uses the simplified scp-like syntax. See the official clone help
[page][git-clone] for details.
[git-clone]: https://git-scm.com/docs/git-clone#_git_urls
When the configuration above is used, the output is the following:
```
$ ./mira -c config.json
Processing config Gitea to Github.
Mira mirrored successfully.
```
It does not support any authentication mechanisms beside what we'll be available
at the shell, which means you should run it in an environment where an SSH agent
will take care of authenticating yourself against the various servers you will
be mirroring from and to.