mirror of
https://github.com/taigrr/github2mr.git
synced 2026-04-02 03:09:09 -07:00
121 lines
5.1 KiB
Markdown
121 lines
5.1 KiB
Markdown
|
|
# Contents
|
|
|
|
* [github2mr](#github2mr)
|
|
* [Brief mr Example](#brief-mr-example)
|
|
* [Installation](#installation)
|
|
* [Configuration / Usage](#configuration--usage)
|
|
* [Other Git Hosts](#other-git-hosts)
|
|
* [Github Setup](#github-setup)
|
|
|
|
|
|
|
|
|
|
# github2mr
|
|
|
|
Many [Github](https://github.com/) users have a large number of repositories upon which they work, and managing them all can sometimes be difficult.
|
|
|
|
One excellent tool which helps a lot is the [myrepos](https://myrepos.branchable.com/) package, containing a binary named `mr`, which allows you to run many operations upon multiple repositories with one command. (It understands git, mercurial, darcs, cvs, and many other types of revision-control systems.)
|
|
|
|
This repository contains a simple command-line client which allows you to easily generate a configuration file containing __all__ your github repositories fetching them via the [Github API](https://developer.github.com/v3/) with various filtering and limiting options.
|
|
|
|
The end result of using `mr` and `github2mr` is that you should be able to clone all your remote github repositories, and update them easily with only a couple of commands which is great for when you work/develop/live on multiple machines.
|
|
|
|
|
|
## Brief `mr` Example
|
|
|
|
Let us pretend I'm moving to a new machine; first of all I export the list of all my remote repositories to a configuration file using _this_ tool:
|
|
|
|
github2mr > ~/Repos/.mrconfig.github
|
|
|
|
* **NOTE**: The first time you create a new configuration file you will need to mark it as being trusted, because it is possible for configuration files to contain arbitrary shell-commands.
|
|
* Mark the configuration file as trusted by adding it's name to `~/.mrtrust`:
|
|
* `echo ~/Repos/.mrconfig.github >> ~/.mrtrust`
|
|
|
|
Now that we've populated a configuration-file we can tell `mr` to checkout each of those repositories:
|
|
|
|
mr --jobs 8 --config ~/Repos/.mrconfig.github
|
|
|
|
Later in the week I can update all the repositories which have been cloned, pulling in any remote changes that have been made from other systems:
|
|
|
|
mr --jobs 8 --config ~/Repos/.mrconfig.github update
|
|
|
|
**NOTE**: If you prefer you can just use `update` all the time, `mr` will checkout a repository if it is missing as part of the `update` process. I'm using distinct flags here for clarity. Please read the `mr`-manpage to look at the commands it understands.
|
|
|
|
|
|
# Installation
|
|
|
|
You should be able to install this application using the standard golang approach:
|
|
|
|
$ go get github.com/skx/github2mr
|
|
|
|
If you prefer you can [download the latest binary](http://github.com/skx/github2mr/releases) release, for various systems.
|
|
|
|
|
|
|
|
|
|
# Configuration / Usage
|
|
|
|
Once installed you'll need to configure your github token, which you can generate from [withing your github settings](https://github.com/settings/tokens).
|
|
|
|
you can either pass the token as an argument to the tool (via `github2mr -token=xxxxx`), or store it in the environment in the variable GITHUB_TOKEN:
|
|
|
|
$ export GITHUB_TOKEN=xxxxx
|
|
$ github2mr [options]
|
|
|
|
You can run `github2mr -help` to see available options, but in brief:
|
|
|
|
* You can choose a default prefix to clone your repositories to.
|
|
* By default all repositories will be located at `~/Repos/${git_host}`.
|
|
* You can exclude all-organizational repositories.
|
|
* Or the reverse, ignoring all personal-repositories.
|
|
* You can exclude repositories by name.
|
|
* You can default to cloning repositories via HTTP, instead of SSH.
|
|
* By default all _archived_ repositories are excluded.
|
|
|
|
|
|
## Other Git Hosts
|
|
|
|
This tool can be configured to point at other systems which use the same
|
|
API as the public-facing Github site.
|
|
|
|
To use it against a self-hosted Github Enterprise installation, for example,
|
|
simply specify the URL:
|
|
|
|
$ export GITHUB_TOKEN=xxxxx
|
|
$ github2mr -api=https://git.example.com/ [options]
|
|
|
|
It has also been tested against an installation of [gitbucket](https://github.com/gitbucket/gitbucket) which can be configured a similar way - however in this case you'll find that you receive an error "401 bad credentials" unless you add the `-auth-header-token` flag:
|
|
|
|
$ export GITHUB_TOKEN=xxxxx
|
|
$ github2mr -api=https://git.example.com/ -auth-header-token
|
|
|
|
This seems to be related to the OAUTH header the library I'm using sends, by default it will send a HTTP request looking like this:
|
|
|
|
```
|
|
GET /api/v3/users/skx/repos HTTP/1.1
|
|
Host: localhost:9999
|
|
User-Agent: go-github
|
|
Accept: application/vnd.github.mercy-preview+json
|
|
Authorization: Bearer SECRET-TOKEN
|
|
Accept-Encoding: gzip
|
|
```
|
|
|
|
Notice that the value of the `Authorization`-header begins with `Bearer`? Gitbucket prefers to see `Authorization: token SECRET-VALUE-HERE`.
|
|
|
|
|
|
|
|
|
|
# Github Setup
|
|
|
|
This repository is configured to run tests upon every commit, and when pull-requests are created/updated. The testing is carried out via [.github/run-tests.sh](.github/run-tests.sh) which is used by the [github-action-tester](https://github.com/skx/github-action-tester) action.
|
|
|
|
Releases are automated in a similar fashion via [.github/build](.github/build), and the [github-action-publish-binaries](https://github.com/skx/github-action-publish-binaries) action.
|
|
|
|
Currently these are reporting failures; but I'm in the process of fixing them.
|
|
|
|
|
|
|
|
Steve
|
|
--
|