README.md

Repoman

Multi-repository management command-line tool with support for Git and Subversion.

Repoman is a handy tool when you're working on multiple related version control repositories. Rather than updating each repository one by one, repoman allows you to just run repoman get and update all of them in one go. Rather than checking for uncommitted local changes one by one, you can run repoman changes or repoman report and check all in one go.

If you often switch between multiple computers, you can use the same .repoman.json file on those computers and easily manage the same set of repositories or share a .repoman.json file with you team so everyone can clone the required set of repositories in one step.

If you are have a GitHub account, you can use Repoman to clone all of your repositories from GitHub with a one liner: repoman config --github-user <user> && repoman init .

Installation

npm install -g repoman

Usage

Initial Configuration

• repoman config: Create sample .repoman.json configuration file.
• repoman config --github-user basti1302: Create .repoman.json containing public GitHub projects of a user.
• repoman config --github-user basti1302 --github-auth-user basti1302 --github-auth-pass somepassword: Create .repoman.json containing private and public GitHub projects. Basic authentication will be used to get the private projects. This will not work if you have two-factor authentication enabled, see repoman signin for support for two factor authentication.
• repoman signin: Starts repoman's GitHub authentication assistant (asking for your GitHub user name, password and a two factor auth token). The generated authentication token is stored in ~/.repomanrc.json and used for subsequent requests to GitHub (for example, with repoman config --github-user username`).
• repoman config --github-org jenkinsci: Create .repoman.json containing GitHub projects of an organisation.
• repoman config --github-user basti1302 --github-org jenkinsci,github: Create .repoman.json containing GitHub projects of multiple users and organisations.
• repoman config --bitbucket-auth-user basti1302 --bitbucket-auth-pass somepassword: Create .repoman.json containing Bitbucket projects.
• repoman config --local: Create .repoman.json configuration file from local repositories in current directory.
• repoman clean: Delete local repositories not managed by Repoman (that is, not configured in .repoman.json).
• repoman add: Add a repository to the repoman configuration and clone it
• repoman remove: Remove a single repository from the configuration and from disk

Initial Clone/Checkout

• repoman init: Initialise local repositories. repoman init clones/checks out all repositories mentioned in .repoman.json into the current folder. You can also run this safely when you already have cloned some of those repositories before, after adding more repositories to the .repoman.json file. Existing repositories/directories will simply be skipped.

Everyday Workflow Commands

• repoman get: Update local repositories with changes from remote repositories. For git, it executes git pull --rebase, for SVN, svn up is executed.
• repoman changes: Display the changes in local repositories.
• repoman report: Display a brief status summary for each repository (branch name, uncommitted changes, unpushed commits). Here is an example of how this looks like:

┌────────────────┬────────────────────────┬─────────────┬──────────┐
│ Repository     │ Branch                 │ Uncommitted │ Unpushed │
│ httpd          │ main                 │ Clean       │ 0        │
│ nodejs         │ feature-branch-xyz     │ Clean       │ 11       │
│ benchmarks     │ main                 │ Clean       │ 0        │
│ internal-tools │ main                 │ Clean       │ 0        │
│ svn-repo       │ trunk                  │ Clean       │ N. A.    │
│ documentation  │ main                 │ Dirty       │ 0        │
│ ui             │ another-feature-branch │ Clean       │ 9        │
└────────────────┴────────────────────────┴─────────────┴──────────┘

• repoman save: Update remote repositories with changes from local repositories.
• repoman delete: Delete local repositories.
• repoman undo: Remove uncommitted changes from local repositories.

Custom commands

• repoman exec <command>: Execute custom command against local repositories.

You can use mustache.js templates in the custom command. The variables workspace and name will be substituted by the workspace directory (where your .repoman.json lives) and the directory name of the repository respectively. Additionally, the variable pathseparator will be replaced by path.sep, that is by \\ on Windows and / on all Unix-based operating systems. Note: It is recommended to use {{{ and }}} instead of {{ and }} to avoid the HTML-escaping mustache.js does for the latter.

Here are some examples for custom commands:

• repoman exec 'touch .gitignore && echo "Created {{{workspace}}}/{{{name}}}/.gitignore file;"': Create a .gitignore file in each repository and print a message.
• repoman --fail-fast exec 'chown -R user:group /some/path/{name}';: Execute custom command and exit as soon as there is any command failure.

Advanced Examples

• repoman list | parallel nestor build {}: Write repository names to standard output and pipe to another command.
• repoman -c somerepoman.json init|get|changes|save|delete|clean|exec|report|list: Use somerepoman.json instead of the default .repoman.json configuration file.
• repoman --tags apache,github init|get|changes|save|delete|exec|report|list: Filter repositories by tags, if multiple tags (comma-separated) are specified then repo will be included if it matches at least one tag.
• repoman --regex .*github.* init|get|changes|save|delete|exec|report|list: Filter repositories by regex against repo name or URL.

Configuration

Repositories can be configured in .repoman.json file:

{
  "couchdb": {
    "type": "git",
    "url": "http://git-wip-us.apache.org/repos/asf/couchdb.git",
    "tags": ["apache", "database"]
  },
  "httpd": {
    "type": "svn",
    "url": "http://svn.apache.org/repos/asf/httpd/httpd/trunk/",
    "tags": ["apache", "webserver"]
  },
  "node": {
    "type": "git",
    "url": "http://github.com/joyent/node",
    "tags": ["github", "javascript"]
  }
}

Type property is optional. If not provided, Repoman will try to determine the type from the URL by checking the existence of keywords: git, svn, subversion. If type can't be determined from the URL, it defaults to git.

Repoman will choose which configuration file to use in this order:

1. Any file specified in -c/--config-file flag
2. .repoman.json file in the current directory
3. .repoman.json file in home directory (process.env.USERPROFILE on Windows, process.env.HOME on *nix)

SCM Command Mappings

Repoman uses the following SCM command mapping.

Repoman	Git	Subversion
repoman init	git clone {url}	svn checkout {url}
repoman get	git pull --rebase	svn up
repoman changes	git status -s && git log --branches --not --remotes --oneline	svn stat
repoman save	git push origin main	svn commit -m "Commited by Repoman"
repoman undo	git reset --hard	svn revert -R .

Contributing

Run npm run build to kick off the full build including tests, integration tests, coverage etc. Note: Currently, the integration tests will fail on systems where git uses a different localization than English.