All patches and comments are welcome. Please squash your changes to logical
commits before using git-format-patch and git-send-email to
patches@git.madduck.net.
If you'd read over the Git project's submission guidelines and adhered to them,
I'd be especially grateful.
7 mr - a Multiple Repository management tool
11 B<mr> [options] checkout
13 B<mr> [options] update
15 B<mr> [options] status
17 B<mr> [options] commit [-m "message"]
23 B<mr> [options] register [repository]
25 B<mr> [options] config section ["parameter=[value]" ...]
27 B<mr> [options] action [params ...]
31 B<mr> is a Multiple Repository management tool. It can checkout, update, or
32 perform other actions on a set of repositories as if they were one combined
33 respository. It supports any combination of subversion, git, cvs, mecurial and
34 bzr repositories, and support for other revision control systems can easily be
37 B<mr> cds into and operates on all registered repositories at or below your
38 working directory. Or, if you are in a subdirectory of a repository that
39 contains no other registered repositories, it will stay in that directory,
40 and work on only that repository,
42 These predefined commands should be fairly familiar to users of any revision
47 =item checkout (or co)
49 Checks out any repositories that are not already checked out.
53 Updates each repository from its configured remote repository.
55 If a repository isn't checked out yet, it will first check it out.
59 Displays a status report for each repository, showing what
60 uncommitted changes are present in the repository.
64 Commits changes to each repository. (By default, changes are pushed to the
65 remote repository too, when using distributed systems like git.)
67 The optional -m parameter allows specifying a commit message.
71 Show a diff of uncommitted changes.
79 These commands are also available:
85 List the repositories that mr will act on.
89 Register an existing repository in a mrconfig file. By default, the
90 repository in the current directory is registered, or you can specify a
91 directory to register.
93 The mrconfig file that is modified is chosen by either the -c option, or by
94 looking for the closest known one at or below the current directory.
98 Adds, modifies, removes, or prints a value from a mrconfig file. The next
99 parameter is the name of the section the value is in. To add or modify
100 values, use one or more instances of "parameter=value". Use "parameter=" to
101 remove a parameter. Use just "parameter" to get the value of a parameter.
103 For example, to add (or edit) a repository in src/foo:
105 mr config src/foo checkout="svn co svn://example.com/foo/trunk foo"
107 To show the command that mr uses to update the repository in src/foo:
109 mr config src/foo update
111 To see the built-in library of shell functions contained in mr:
113 mr config DEFAULT lib
115 The ~/.mrconfig file is used by default. To use a different config file,
124 Actions can be abbreviated to any unambiguous subsctring, so
125 "mr st" is equivilant to "mr status", and "mr up" is equivilant to "mr
128 Additional parameters can be passed to most commands, and are passed on
129 unchanged to the underlying revision control system. This is mostly useful
130 if the repositories mr will act on all use the same revision control
139 Specifies the topmost directory that B<mr> should work in. The default is
140 the current working directory.
144 Use the specified mrconfig file. The default is B<~/.mrconfig>
152 Expand the statistics line displayed at the end to include information
153 about exactly which repositories failed and were skipped, if any.
157 Just operate on the repository for the current directory, do not
158 recurse into deeper repositories.
162 Run the specified number of jobs in parallel. This can greatly speed up
163 operations such as updates.
165 Note that in -j mode, all output of the jobs goes to standard output, even
166 output that would normally go to standard error.
172 B<mr> is configured by .mrconfig files. It starts by reading the .mrconfig
173 file in your home directory, and this can in turn chain load .mrconfig files
176 Here is an example .mrconfig file:
179 checkout = svn co svn://svn.example.com/src/trunk src
183 checkout = git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git &&
185 git checkout -b mybranch origin/master
187 The .mrconfig file uses a variant of the INI file format. Lines starting with
188 "#" are comments. Values can be continued to the following line by
189 indenting the line with whitespace.
191 The "DEFAULT" section allows setting default values for the sections that
194 The "ALIAS" section allows adding aliases for actions. Each parameter
195 is an alias, and its value is the action to use.
197 All other sections add repositories. The section header specifies the
198 directory where the repository is located. This is relative to the directory
199 that contains the mrconfig file, but you can also choose to use absolute
202 Within a section, each parameter defines a shell command to run to handle a
203 given action. mr contains default handlers for "update", "status",
204 "commit", and other standard actions. Normally you only need to specify what
205 to do for "checkout".
207 Note that these shell commands are run in a "set -e" shell
208 environment, where any additional parameters you pass are available in
209 "$@". The "checkout" command is run in the parent of the repository
210 directory, since the repository isn't checked out yet. All other commands
211 are run inside the repository, though not necessarily at the top of it.
213 The "MR_REPO" environment variable is set to the path to the top of the
214 repository. The "MR_CONFIG" environment variable is set to the .mrconfig file
215 that defines the repo being acted on, or, if the repo is not yet in a config
216 file, the .mrconfig file that should be modified to register the repo.
218 A few parameters have special meanings:
224 If the "skip" parameter is set and its command returns true, then B<mr>
225 will skip acting on that repository. The command is passed the action
228 Here are two examples. The first skips the repo unless
229 mr is run by joey. The second uses the hours_since function
230 (included in mr's built-in library) to skip updating the repo unless it's
231 been at least 12 hours since the last update.
233 skip = test $(whoami) != joey
234 skip = [ "$1" = update ] && [ $(hours_since "$1") -lt 12 ]
238 If the "chain" parameter is set and its command returns true, then B<mr>
239 will try to load a .mrconfig file from the root of the repository. (You
240 should avoid chaining from repositories with untrusted committers.)
244 The "lib" parameter can specify some shell code that will be run before each
245 command, this can be a useful way to define shell functions for other commands
252 Copyright 2007 Joey Hess <joey@kitenet.net>
254 Licensed under the GNU GPL version 2 or higher.
256 http://kitenet.net/~joey/code/mr/
265 use Cwd qw(getcwd abs_path);
275 print STDERR "mr: interrupted\n";
279 $ENV{MR_CONFIG}="$ENV{HOME}/.mrconfig";
280 my $config_overridden=0;
281 my $directory=getcwd();
291 Getopt::Long::Configure("no_permute");
292 my $result=GetOptions(
293 "d|directory=s" => sub { $directory=abs_path($_[1]) },
294 "c|config=s" => sub { $ENV{MR_CONFIG}=$_[1]; $config_overridden=1 },
295 "v|verbose" => \$verbose,
296 "s|stats" => \$stats,
297 "n|no-recurse" => \$no_recurse,
298 "j|jobs=i" => \$jobs,
300 if (! $result || @ARGV < 1) {
301 die("Usage: mr [-d directory] action [params ...]\n".
302 "(Use mr help for man page.)\n");
306 # Make sure MR_CONFIG is an absolute path, but don't use abs_path since
307 # the config file might be a symlink to elsewhere, and the directory it's
309 if ($ENV{MR_CONFIG} !~ /^\//) {
310 $ENV{MR_CONFIG}=getcwd()."/".$ENV{MR_CONFIG};
312 # Try to set MR_PATH to the path to the program.
314 use FindBin qw($Bin $Script);
315 $ENV{MR_PATH}=$Bin."/".$Script;
319 loadconfig($ENV{MR_CONFIG});
321 #print Dumper(\%config);
323 # alias expansion and command stemming
324 my $action=shift @ARGV;
325 if (exists $alias{$action}) {
326 $action=$alias{$action};
328 if (! exists $knownactions{$action}) {
329 my @matches = grep { /^\Q$action\E/ }
330 keys %knownactions, keys %alias;
334 elsif (@matches == 0) {
335 die "mr: unknown action \"$action\" (known actions: ".
336 join(", ", sort keys %knownactions).")\n";
339 die "mr: ambiguous action \"$action\" (matches: ".
340 join(", ", @matches).")\n";
344 # commands that do not operate on all repos
345 if ($action eq 'help') {
346 exec($config{''}{DEFAULT}{$action}) || die "exec: $!";
348 elsif ($action eq 'config') {
350 die "mr config: not enough parameters\n";
353 if ($section=~/^\//) {
354 # try to convert to a path relative to the config file
355 my ($dir)=$ENV{MR_CONFIG}=~/^(.*\/)[^\/]+$/;
357 $dir.="/" unless $dir=~/\/$/;
358 if ($section=~/^\Q$dir\E(.*)/) {
364 if (/^([^=]+)=(.*)$/) {
365 $changefields{$1}=$2;
369 foreach my $topdir (sort keys %config) {
370 if (exists $config{$topdir}{$section} &&
371 exists $config{$topdir}{$section}{$_}) {
372 print $config{$topdir}{$section}{$_}."\n";
374 last if $section eq 'DEFAULT';
378 die "mr $action: $section $_ not set\n";
382 modifyconfig($ENV{MR_CONFIG}, $section, %changefields) if %changefields;
385 elsif ($action eq 'register') {
386 if (! $config_overridden) {
387 # Find the closest known mrconfig file to the current
389 $directory.="/" unless $directory=~/\/$/;
390 foreach my $topdir (reverse sort keys %config) {
391 next unless length $topdir;
392 if ($directory=~/^\Q$topdir\E/) {
393 $ENV{MR_CONFIG}=$configfiles{$topdir};
398 my $command="set -e; ".$config{''}{DEFAULT}{lib}."\n".
399 "my_action(){ $config{''}{DEFAULT}{$action}\n }; my_action ".
400 join(" ", map { s/\//\/\//g; s/"/\"/g; '"'.$_.'"' } @ARGV);
401 print STDERR "mr $action: running >>$command<<\n" if $verbose;
402 exec($command) || die "exec: $!";
405 # work out what repos to act on
408 foreach my $topdir (sort keys %config) {
409 foreach my $subdir (sort keys %{$config{$topdir}}) {
410 next if $subdir eq 'DEFAULT';
411 my $dir=($subdir =~/^\//) ? $subdir : $topdir.$subdir;
413 $dir.="/" unless $dir=~/\/$/;
414 $d.="/" unless $d=~/\/$/;
415 next if $no_recurse && $d ne $dir;
416 next if $dir ne $d && $dir !~ /^\Q$d\E/;
417 push @repos, [$dir, $topdir, $subdir];
421 # fallback to find a leaf repo
422 LEAF: foreach my $topdir (reverse sort keys %config) {
423 foreach my $subdir (reverse sort keys %{$config{$topdir}}) {
424 next if $subdir eq 'DEFAULT';
425 my $dir=($subdir =~/^\//) ? $subdir : $topdir.$subdir;
427 $dir.="/" unless $dir=~/\/$/;
428 $d.="/" unless $d=~/\/$/;
429 if ($d=~/^\Q$dir\E/) {
430 push @repos, [$dir, $topdir, $subdir];
438 # run the action on each repository and print stats
439 my (@ok, @failed, @skipped);
444 foreach my $repo (@repos) {
445 record($repo, action($action, @$repo));
448 if (! @ok && ! @failed && ! @skipped) {
449 die "mr $action: no repositories found to work on\n";
451 print "mr $action: finished (".join("; ",
452 showstat($#ok+1, "ok", "ok"),
453 showstat($#failed+1, "failed", "failed"),
454 showstat($#skipped+1, "skipped", "skipped"),
458 print "mr $action: (skipped: ".join(" ", @skipped).")\n";
461 print STDERR "mr $action: (failed: ".join(" ", @failed).")\n";
467 elsif (! @ok && @skipped) {
473 my ($action, $dir, $topdir, $subdir) = @_;
475 $ENV{MR_CONFIG}=$configfiles{$topdir};
476 my $lib=exists $config{$topdir}{$subdir}{lib} ?
477 $config{$topdir}{$subdir}{lib}."\n" : "";
479 if ($action eq 'checkout') {
481 print "mr $action: $dir already exists, skipping checkout\n" if $verbose;
485 $dir=~s/^(.*)\/[^\/]+\/?$/$1/;
488 print "mr $action: creating parent directory $dir\n" if $verbose;
489 system("mkdir", "-p", $dir);
492 elsif ($action eq 'update') {
494 return action("checkout", $dir, $topdir, $subdir);
500 if (exists $config{$topdir}{$subdir}{skip}) {
501 my $test="set -e;".$lib.
502 "my_action(){ $config{$topdir}{$subdir}{skip}\n }; my_action '$action'";
503 print "mr $action: running skip test >>$test<<\n" if $verbose;
504 my $ret=system($test);
506 if (($? & 127) == 2) {
507 print STDERR "mr $action: interrupted\n";
511 print STDERR "mr $action: skip test received signal ".($? & 127)."\n";
515 if ($ret >> 8 == 0) {
516 print "mr $action: $dir skipped per config file\n" if $verbose;
521 if (! $nochdir && ! chdir($dir)) {
522 print STDERR "mr $action: failed to chdir to $dir: $!\n";
525 elsif (! exists $config{$topdir}{$subdir}{$action}) {
526 print STDERR "mr $action: no defined $action command for $topdir$subdir, skipping\n";
531 print "mr $action: $topdir$subdir\n";
534 print "mr $action: $topdir$subdir (in subdir $directory)\n";
536 my $command="set -e; ".$lib.
537 "my_action(){ $config{$topdir}{$subdir}{$action}\n }; my_action ".
538 join(" ", map { s/\//\/\//g; s/"/\"/g; '"'.$_.'"' } @ARGV);
539 print STDERR "mr $action: running >>$command<<\n" if $verbose;
540 my $ret=system($command);
543 if (($? & 127) == 2) {
544 print STDERR "mr $action: interrupted\n";
548 print STDERR "mr $action: received signal ".($? & 127)."\n";
551 print STDERR "mr $action: failed ($ret)\n" if $verbose;
552 if ($ret >> 8 != 0) {
553 print STDERR "mr $action: command failed\n";
556 print STDERR "mr $action: command died ($ret)\n";
561 if ($action eq 'checkout' && ! -d $dir) {
562 print STDERR "mr $action: $dir missing after checkout\n";;
571 # run actions on multiple repos, in parallel
578 while (@fhs or @repos) {
579 while ($running < $jobs && @repos) {
581 my $repo = shift @repos;
582 my $pid = open(my $fh, "-|");
584 open(STDERR, ">&STDOUT");
585 exit action($action, @$repo);
591 my ($rin, $rout) = ('','', '');
593 foreach my $x (@fhs) {
594 next unless defined $x;
595 vec($rin, fileno($x), 1) = 1;
597 $nfound = select($rout=$rin, undef, undef, 1);
598 foreach my $i (0..$#fhs) {
600 next unless defined $fh;
601 if (vec($rout, fileno($fh), 1) == 1) {
603 if (sysread($fh, $r, 1024) == 0) {
605 record($active[$i], $? >> 8);
614 while (@fhs and !defined $fhs[0]) {
623 my $dir=shift()->[0];
629 elsif ($ret == FAILED) {
632 elsif ($ret == SKIPPED) {
635 elsif ($ret == ABORT) {
639 die "unknown exit status $ret";
648 return "$count ".($count > 1 ? $plural : $singular);
654 sub loadconfig { #{{{
661 if (ref $f eq 'GLOB') {
670 my $absf=abs_path($f);
671 if ($loaded{$absf}) {
676 ($dir)=$f=~/^(.*\/)[^\/]+$/;
677 if (! defined $dir) {
680 $dir=abs_path($dir)."/";
682 if (! exists $configfiles{$dir}) {
683 $configfiles{$dir}=$f;
686 # copy in defaults from first parent
688 while ($parent=~s/^(.*\/)[^\/]+\/?$/$1/) {
689 if ($parent eq '/') {
692 if (exists $config{$parent} &&
693 exists $config{$parent}{DEFAULT}) {
694 $config{$dir}{DEFAULT}={ %{$config{$parent}{DEFAULT}} };
699 print "mr: loading config $f\n" if $verbose;
700 open($in, "<", $f) || die "mr: open $f: $!\n";
711 next if /^\s*\#/ || /^\s*$/;
712 if (/^\[([^\]]*)\]\s*$/) {
715 elsif (/^(\w+)\s*=\s*(.*)/) {
720 while (@lines && $lines[0]=~/^\s(.+)/) {
727 if (! defined $section) {
728 die "$f line $.: parameter ($parameter) not in section\n";
730 if ($section ne 'ALIAS' &&
731 ! exists $config{$dir}{$section} &&
732 exists $config{$dir}{DEFAULT}) {
734 $config{$dir}{$section}={ %{$config{$dir}{DEFAULT}} };
736 if ($section eq 'ALIAS') {
737 $alias{$parameter}=$value;
739 elsif ($parameter eq 'lib') {
740 $config{$dir}{$section}{lib}.=$value."\n";
743 $config{$dir}{$section}{$parameter}=$value;
744 $knownactions{$parameter}=1;
745 if ($parameter eq 'chain' &&
746 length $dir && $section ne "DEFAULT" &&
747 -e $dir.$section."/.mrconfig") {
748 my $ret=system($value);
750 if (($? & 127) == 2) {
751 print STDERR "mr $action: chain test interrupted\n";
755 print STDERR "mr $action: chain test received signal ".($? & 127)."\n";
759 push @toload, $dir.$section."/.mrconfig";
765 die "$f line $line: parse error\n";
774 sub modifyconfig { #{{{
776 # the section to modify or add
777 my $targetsection=shift;
778 # fields to change in the section
779 # To remove a field, set its value to "".
786 open(my $in, "<", $f) || die "mr: open $f: $!\n";
791 my $formatfield=sub {
793 my @value=split(/\n/, shift);
795 return "$field = ".shift(@value)."\n".
796 join("", map { "\t$_\n" } @value);
800 while ($out[$#out] =~ /^\s*$/) {
801 unshift @blanks, pop @out;
803 foreach my $field (sort keys %changefields) {
804 if (length $changefields{$field}) {
805 push @out, "$field = $changefields{$field}\n";
806 delete $changefields{$field};
816 if (/^\s*\#/ || /^\s*$/) {
819 elsif (/^\[([^\]]*)\]\s*$/) {
820 if (defined $section &&
821 $section eq $targetsection) {
829 elsif (/^(\w+)\s*=\s(.*)/) {
834 while (@lines && $lines[0]=~/^\s(.+)/) {
840 if ($section eq $targetsection) {
841 if (exists $changefields{$parameter}) {
842 if (length $changefields{$parameter}) {
843 $value=$changefields{$parameter};
845 delete $changefields{$parameter};
849 push @out, $formatfield->($parameter, $value);
853 if (defined $section &&
854 $section eq $targetsection) {
857 elsif (%changefields) {
858 push @out, "\n[$targetsection]\n";
859 foreach my $field (sort keys %changefields) {
860 if (length $changefields{$field}) {
861 push @out, $formatfield->($field, $changefields{$field});
866 open(my $out, ">", $f) || die "mr: write $f: $!\n";
871 # Finally, some useful actions that mr knows about by default.
872 # These can be overridden in ~/.mrconfig.
887 for dir in .git .svn .bzr CVS .hg; do
888 if [ -e "$MR_REPO/$dir" ]; then
889 flagfile="$MR_REPO/$dir/.mr_last$1"
893 if [ -z "$flagfile" ]; then
894 error "cannot determine flag filename"
896 perl -wle 'print -f shift() ? int((-M _) * 24) : 9999' "$flagfile"
901 if [ -d "$MR_REPO"/.svn ]; then
903 elif [ -d "$MR_REPO"/.git ]; then
905 git pull -t origin master
909 elif [ -d "$MR_REPO"/.bzr ]; then
911 elif [ -d "$MR_REPO"/CVS ]; then
913 elif [ -d "$MR_REPO"/.hg ]; then
914 hg pull "$@" && hg update "$@"
916 error "unknown repo type"
919 if [ -d "$MR_REPO"/.svn ]; then
921 elif [ -d "$MR_REPO"/.git ]; then
922 git status "$@" || true
923 elif [ -d "$MR_REPO"/.bzr ]; then
925 elif [ -d "$MR_REPO"/CVS ]; then
927 elif [ -d "$MR_REPO"/.hg ]; then
930 error "unknown repo type"
933 if [ -d "$MR_REPO"/.svn ]; then
935 elif [ -d "$MR_REPO"/.git ]; then
936 git commit -a "$@" && git push --all
937 elif [ -d "$MR_REPO"/.bzr ]; then
938 bzr commit "$@" && bzr push
939 elif [ -d "$MR_REPO"/CVS ]; then
941 elif [ -d "$MR_REPO"/.hg ]; then
942 hg commit -m "$@" && hg push
944 error "unknown repo type"
947 if [ -d "$MR_REPO"/.svn ]; then
949 elif [ -d "$MR_REPO"/.git ]; then
951 elif [ -d "$MR_REPO"/.bzr ]; then
953 elif [ -d "$MR_REPO"/CVS ]; then
955 elif [ -d "$MR_REPO"/.hg ]; then
958 error "unknown repo type"
961 if [ -d "$MR_REPO"/.svn ]; then
963 elif [ -d "$MR_REPO"/.git ]; then
965 elif [ -d "$MR_REPO"/.bzr ]; then
967 elif [ -d "$MR_REPO"/CVS ]; then
969 elif [ -d "$MR_REPO"/.hg ]; then
972 error "unknown repo type"
978 basedir="$(basename $(pwd))"
980 url=$(LANG=C svn info . | grep -i ^URL: | cut -d ' ' -f 2)
981 if [ -z "$url" ]; then
982 error "cannot determine svn url"
984 echo "Registering svn url: $url in $MR_CONFIG"
985 mr -c "$MR_CONFIG" config "$(pwd)" checkout="svn co $url $basedir"
986 elif [ -d .git ]; then
987 url=$(LANG=C git-config --get remote.origin.url)
988 if [ -z "$url" ]; then
989 error "cannot determine git url"
991 echo "Registering git url: $url in $MR_CONFIG"
992 mr -c "$MR_CONFIG" config "$(pwd)" checkout="git clone $url $basedir"
993 elif [ -d .bzr ]; then
994 url=$(cat .bzr/branch/parent)
995 if [ -z "$url" ]; then
996 error "cannot determine bzr url"
998 echo "Registering bzr url: $url in $MR_CONFIG"
999 mr -c "$MR_CONFIG" config "$(pwd)" checkout="bzr clone $url $basedir"
1000 elif [ -d CVS ]; then
1001 repo=$(cat CVS/Repository)
1002 root=$(cat CVS/Root)
1003 if [ -z "$root" ]; then
1004 error "cannot determine cvs root"
1006 echo "Registering cvs repository $repo at root $root"
1007 mr -c "$MR_CONFIG" config "$(pwd)" \
1008 checkout="cvs -d '$root' co -d $basedir $repo"
1009 elif [ -d .hg ]; then
1010 url=$(hg showconfig paths.default)
1011 echo "Registering mercurial repo url: $url in $MR_CONFIG"
1012 mr -c "$MR_CONFIG" config "$(pwd)" \
1013 checkout="hg clone $url $basedir"
1015 error "unable to register this repo type"
1018 if [ ! -e "$MR_PATH" ]; then
1019 error "cannot find program path"
1021 (pod2man -c mr "$MR_PATH" | man -l -) || error "pod2man or man failed"
1025 ed = echo "A horse is a horse, of course, of course.."
1026 T = echo "I pity the fool."
1027 right = echo "Not found."