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. It is not recommended for interactive
170 B<mr> is configured by .mrconfig files. It starts by reading the .mrconfig
171 file in your home directory, and this can in turn chain load .mrconfig files
174 Here is an example .mrconfig file:
177 checkout = svn co svn://svn.example.com/src/trunk src
181 checkout = git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git &&
183 git checkout -b mybranch origin/master
185 The .mrconfig file uses a variant of the INI file format. Lines starting with
186 "#" are comments. Values can be continued to the following line by
187 indenting the line with whitespace.
189 The "DEFAULT" section allows setting default values for the sections that
192 The "ALIAS" section allows adding aliases for actions. Each parameter
193 is an alias, and its value is the action to use.
195 All other sections add repositories. The section header specifies the
196 directory where the repository is located. This is relative to the directory
197 that contains the mrconfig file, but you can also choose to use absolute
200 Within a section, each parameter defines a shell command to run to handle a
201 given action. mr contains default handlers for "update", "status",
202 "commit", and other standard actions. Normally you only need to specify what
203 to do for "checkout".
205 Note that these shell commands are run in a "set -e" shell
206 environment, where any additional parameters you pass are available in
207 "$@". The "checkout" command is run in the parent of the repository
208 directory, since the repository isn't checked out yet. All other commands
209 are run inside the repository, though not necessarily at the top of it.
211 The "MR_REPO" environment variable is set to the path to the top of the
212 repository. The "MR_CONFIG" environment variable is set to the .mrconfig file
213 that defines the repo being acted on, or, if the repo is not yet in a config
214 file, the .mrconfig file that should be modified to register the repo.
216 A few parameters have special meanings:
222 If the "skip" parameter is set and its command returns true, then B<mr>
223 will skip acting on that repository. The command is passed the action
226 Here are two examples. The first skips the repo unless
227 mr is run by joey. The second uses the hours_since function
228 (included in mr's built-in library) to skip updating the repo unless it's
229 been at least 12 hours since the last update.
231 skip = test $(whoami) != joey
232 skip = [ "$1" = update ] && [ $(hours_since "$1") -lt 12 ]
236 If the "chain" parameter is set and its command returns true, then B<mr>
237 will try to load a .mrconfig file from the root of the repository. (You
238 should avoid chaining from repositories with untrusted committers.)
242 The "lib" parameter can specify some shell code that will be run before each
243 command, this can be a useful way to define shell functions for other commands
250 Copyright 2007 Joey Hess <joey@kitenet.net>
252 Licensed under the GNU GPL version 2 or higher.
254 http://kitenet.net/~joey/code/mr/
263 use Cwd qw(getcwd abs_path);
273 print STDERR "mr: interrupted\n";
277 $ENV{MR_CONFIG}="$ENV{HOME}/.mrconfig";
278 my $config_overridden=0;
279 my $directory=getcwd();
289 Getopt::Long::Configure("no_permute");
290 my $result=GetOptions(
291 "d|directory=s" => sub { $directory=abs_path($_[1]) },
292 "c|config=s" => sub { $ENV{MR_CONFIG}=$_[1]; $config_overridden=1 },
293 "v|verbose" => \$verbose,
294 "s|stats" => \$stats,
295 "n|no-recurse" => \$no_recurse,
296 "j|jobs=i" => \$jobs,
298 if (! $result || @ARGV < 1) {
299 die("Usage: mr [-d directory] action [params ...]\n".
300 "(Use mr help for man page.)\n");
304 # Make sure MR_CONFIG is an absolute path, but don't use abs_path since
305 # the config file might be a symlink to elsewhere, and the directory it's
307 if ($ENV{MR_CONFIG} !~ /^\//) {
308 $ENV{MR_CONFIG}=getcwd()."/".$ENV{MR_CONFIG};
310 # Try to set MR_PATH to the path to the program.
312 use FindBin qw($Bin $Script);
313 $ENV{MR_PATH}=$Bin."/".$Script;
317 loadconfig($ENV{MR_CONFIG});
319 #print Dumper(\%config);
321 # alias expansion and command stemming
322 my $action=shift @ARGV;
323 if (exists $alias{$action}) {
324 $action=$alias{$action};
326 if (! exists $knownactions{$action}) {
327 my @matches = grep { /^\Q$action\E/ }
328 keys %knownactions, keys %alias;
332 elsif (@matches == 0) {
333 die "mr: unknown action \"$action\" (known actions: ".
334 join(", ", sort keys %knownactions).")\n";
337 die "mr: ambiguous action \"$action\" (matches: ".
338 join(", ", @matches).")\n";
342 # commands that do not operate on all repos
343 if ($action eq 'help') {
344 exec($config{''}{DEFAULT}{$action}) || die "exec: $!";
346 elsif ($action eq 'config') {
348 die "mr config: not enough parameters\n";
351 if ($section=~/^\//) {
352 # try to convert to a path relative to the config file
353 my ($dir)=$ENV{MR_CONFIG}=~/^(.*\/)[^\/]+$/;
355 $dir.="/" unless $dir=~/\/$/;
356 if ($section=~/^\Q$dir\E(.*)/) {
362 if (/^([^=]+)=(.*)$/) {
363 $changefields{$1}=$2;
367 foreach my $topdir (sort keys %config) {
368 if (exists $config{$topdir}{$section} &&
369 exists $config{$topdir}{$section}{$_}) {
370 print $config{$topdir}{$section}{$_}."\n";
372 last if $section eq 'DEFAULT';
376 die "mr $action: $section $_ not set\n";
380 modifyconfig($ENV{MR_CONFIG}, $section, %changefields) if %changefields;
383 elsif ($action eq 'register') {
384 if (! $config_overridden) {
385 # Find the closest known mrconfig file to the current
387 $directory.="/" unless $directory=~/\/$/;
388 foreach my $topdir (reverse sort keys %config) {
389 next unless length $topdir;
390 if ($directory=~/^\Q$topdir\E/) {
391 $ENV{MR_CONFIG}=$configfiles{$topdir};
396 my $command="set -e; ".$config{''}{DEFAULT}{lib}."\n".
397 "my_action(){ $config{''}{DEFAULT}{$action}\n }; my_action ".
398 join(" ", map { s/\//\/\//g; s/"/\"/g; '"'.$_.'"' } @ARGV);
399 print STDERR "mr $action: running >>$command<<\n" if $verbose;
400 exec($command) || die "exec: $!";
403 # work out what repos to act on
406 foreach my $topdir (sort keys %config) {
407 foreach my $subdir (sort keys %{$config{$topdir}}) {
408 next if $subdir eq 'DEFAULT';
409 my $dir=($subdir =~/^\//) ? $subdir : $topdir.$subdir;
411 $dir.="/" unless $dir=~/\/$/;
412 $d.="/" unless $d=~/\/$/;
413 next if $no_recurse && $d ne $dir;
414 next if $dir ne $d && $dir !~ /^\Q$d\E/;
415 push @repos, [$dir, $topdir, $subdir];
419 # fallback to find a leaf repo
420 LEAF: foreach my $topdir (reverse sort keys %config) {
421 foreach my $subdir (reverse sort keys %{$config{$topdir}}) {
422 next if $subdir eq 'DEFAULT';
423 my $dir=($subdir =~/^\//) ? $subdir : $topdir.$subdir;
425 $dir.="/" unless $dir=~/\/$/;
426 $d.="/" unless $d=~/\/$/;
427 if ($d=~/^\Q$dir\E/) {
428 push @repos, [$dir, $topdir, $subdir];
436 # run the action on each repository and print stats
437 my (@ok, @failed, @skipped);
442 foreach my $repo (@repos) {
443 record($repo, action($action, @$repo));
447 if (! @ok && ! @failed && ! @skipped) {
448 die "mr $action: no repositories found to work on\n";
450 print "mr $action: finished (".join("; ",
451 showstat($#ok+1, "ok", "ok"),
452 showstat($#failed+1, "failed", "failed"),
453 showstat($#skipped+1, "skipped", "skipped"),
457 print "mr $action: (skipped: ".join(" ", @skipped).")\n";
460 print STDERR "mr $action: (failed: ".join(" ", @failed).")\n";
466 elsif (! @ok && @skipped) {
472 my ($action, $dir, $topdir, $subdir) = @_;
474 $ENV{MR_CONFIG}=$configfiles{$topdir};
475 my $lib=exists $config{$topdir}{$subdir}{lib} ?
476 $config{$topdir}{$subdir}{lib}."\n" : "";
478 if ($action eq 'checkout') {
480 print "mr $action: $dir already exists, skipping checkout\n" if $verbose;
484 $dir=~s/^(.*)\/[^\/]+\/?$/$1/;
487 print "mr $action: creating parent directory $dir\n" if $verbose;
488 system("mkdir", "-p", $dir);
491 elsif ($action =~ /update/) {
493 return action("checkout", $dir, $topdir, $subdir);
499 if (exists $config{$topdir}{$subdir}{skip}) {
500 my $test="set -e;".$lib.
501 "my_action(){ $config{$topdir}{$subdir}{skip}\n }; my_action '$action'";
502 print "mr $action: running skip test >>$test<<\n" if $verbose;
503 my $ret=system($test);
505 if (($? & 127) == 2) {
506 print STDERR "mr $action: interrupted\n";
510 print STDERR "mr $action: skip test received signal ".($? & 127)."\n";
514 if ($ret >> 8 == 0) {
515 print "mr $action: $dir skipped per config file\n" if $verbose;
520 if (! $nochdir && ! chdir($dir)) {
521 print STDERR "mr $action: failed to chdir to $dir: $!\n";
524 elsif (! exists $config{$topdir}{$subdir}{$action}) {
525 print STDERR "mr $action: no defined $action command for $topdir$subdir, skipping\n";
530 print "mr $action: $topdir$subdir\n";
533 print "mr $action: $topdir$subdir (in subdir $directory)\n";
535 my $command="set -e; ".$lib.
536 "my_action(){ $config{$topdir}{$subdir}{$action}\n }; my_action ".
537 join(" ", map { s/\//\/\//g; s/"/\"/g; '"'.$_.'"' } @ARGV);
538 print STDERR "mr $action: running >>$command<<\n" if $verbose;
539 my $ret=system($command);
541 if (($? & 127) == 2) {
542 print STDERR "mr $action: interrupted\n";
546 print STDERR "mr $action: received signal ".($? & 127)."\n";
549 print STDERR "mr $action: failed ($ret)\n" if $verbose;
550 if ($ret >> 8 != 0) {
551 print STDERR "mr $action: command failed\n";
554 print STDERR "mr $action: command died ($ret)\n";
559 if ($action eq 'checkout' && ! -d $dir) {
560 print STDERR "mr $action: $dir missing after checkout\n";;
569 # run actions on multiple repos, in parallel
576 while (@fhs or @repos) {
577 while ($running < $jobs && @repos) {
579 my $repo = shift @repos;
580 pipe(my $outfh, CHILD_STDOUT);
581 pipe(my $errfh, CHILD_STDERR);
583 unless ($pid = fork) {
584 die "mr $action: cannot fork: $!" unless defined $pid;
585 open(STDOUT, ">&CHILD_STDOUT") || die "mr $action cannot reopen stdout: $!";
586 open(STDERR, ">&CHILD_STDERR") || die "mr $action cannot reopen stderr: $!";
591 exit action($action, @$repo);
595 push @active, [$pid, $repo];
596 push @fhs, [$outfh, $errfh];
599 my ($rin, $rout) = ('','');
601 foreach my $fh (@fhs) {
602 next unless defined $fh;
603 vec($rin, fileno($fh->[0]), 1) = 1 if defined $fh->[0];
604 vec($rin, fileno($fh->[1]), 1) = 1 if defined $fh->[1];
606 $nfound = select($rout=$rin, undef, undef, 1);
607 foreach my $channel (0, 1) {
608 foreach my $i (0..$#fhs) {
609 next unless defined $fhs[$i];
610 my $fh = $fhs[$i][$channel];
611 next unless defined $fh;
612 if (vec($rout, fileno($fh), 1) == 1) {
614 if (sysread($fh, $r, 1024) == 0) {
616 $fhs[$i][$channel] = undef;
617 if (! defined $fhs[$i][0] &&
618 ! defined $fhs[$i][1]) {
619 waitpid($active[$i][0], 0);
620 print STDOUT $out[$i][0];
621 print STDERR $out[$i][1];
623 record($active[$i][1], $? >> 8);
625 splice(@active, $i, 1);
630 $out[$i][$channel] .= $r;
638 my $dir=shift()->[0];
644 elsif ($ret == FAILED) {
647 elsif ($ret == SKIPPED) {
650 elsif ($ret == ABORT) {
654 die "unknown exit status $ret";
663 return "$count ".($count > 1 ? $plural : $singular);
669 sub loadconfig { #{{{
676 if (ref $f eq 'GLOB') {
685 my $absf=abs_path($f);
686 if ($loaded{$absf}) {
691 ($dir)=$f=~/^(.*\/)[^\/]+$/;
692 if (! defined $dir) {
695 $dir=abs_path($dir)."/";
697 if (! exists $configfiles{$dir}) {
698 $configfiles{$dir}=$f;
701 # copy in defaults from first parent
703 while ($parent=~s/^(.*\/)[^\/]+\/?$/$1/) {
704 if ($parent eq '/') {
707 if (exists $config{$parent} &&
708 exists $config{$parent}{DEFAULT}) {
709 $config{$dir}{DEFAULT}={ %{$config{$parent}{DEFAULT}} };
714 print "mr: loading config $f\n" if $verbose;
715 open($in, "<", $f) || die "mr: open $f: $!\n";
726 next if /^\s*\#/ || /^\s*$/;
727 if (/^\[([^\]]*)\]\s*$/) {
730 elsif (/^(\w+)\s*=\s*(.*)/) {
735 while (@lines && $lines[0]=~/^\s(.+)/) {
742 if (! defined $section) {
743 die "$f line $.: parameter ($parameter) not in section\n";
745 if ($section ne 'ALIAS' &&
746 ! exists $config{$dir}{$section} &&
747 exists $config{$dir}{DEFAULT}) {
749 $config{$dir}{$section}={ %{$config{$dir}{DEFAULT}} };
751 if ($section eq 'ALIAS') {
752 $alias{$parameter}=$value;
754 elsif ($parameter eq 'lib') {
755 $config{$dir}{$section}{lib}.=$value."\n";
758 $config{$dir}{$section}{$parameter}=$value;
759 $knownactions{$parameter}=1;
760 if ($parameter eq 'chain' &&
761 length $dir && $section ne "DEFAULT" &&
762 -e $dir.$section."/.mrconfig") {
763 my $ret=system($value);
765 if (($? & 127) == 2) {
766 print STDERR "mr $action: chain test interrupted\n";
770 print STDERR "mr $action: chain test received signal ".($? & 127)."\n";
774 push @toload, $dir.$section."/.mrconfig";
780 die "$f line $line: parse error\n";
789 sub modifyconfig { #{{{
791 # the section to modify or add
792 my $targetsection=shift;
793 # fields to change in the section
794 # To remove a field, set its value to "".
801 open(my $in, "<", $f) || die "mr: open $f: $!\n";
806 my $formatfield=sub {
808 my @value=split(/\n/, shift);
810 return "$field = ".shift(@value)."\n".
811 join("", map { "\t$_\n" } @value);
815 while ($out[$#out] =~ /^\s*$/) {
816 unshift @blanks, pop @out;
818 foreach my $field (sort keys %changefields) {
819 if (length $changefields{$field}) {
820 push @out, "$field = $changefields{$field}\n";
821 delete $changefields{$field};
831 if (/^\s*\#/ || /^\s*$/) {
834 elsif (/^\[([^\]]*)\]\s*$/) {
835 if (defined $section &&
836 $section eq $targetsection) {
844 elsif (/^(\w+)\s*=\s(.*)/) {
849 while (@lines && $lines[0]=~/^\s(.+)/) {
855 if ($section eq $targetsection) {
856 if (exists $changefields{$parameter}) {
857 if (length $changefields{$parameter}) {
858 $value=$changefields{$parameter};
860 delete $changefields{$parameter};
864 push @out, $formatfield->($parameter, $value);
868 if (defined $section &&
869 $section eq $targetsection) {
872 elsif (%changefields) {
873 push @out, "\n[$targetsection]\n";
874 foreach my $field (sort keys %changefields) {
875 if (length $changefields{$field}) {
876 push @out, $formatfield->($field, $changefields{$field});
881 open(my $out, ">", $f) || die "mr: write $f: $!\n";
886 # Finally, some useful actions that mr knows about by default.
887 # These can be overridden in ~/.mrconfig.
902 for dir in .git .svn .bzr CVS .hg; do
903 if [ -e "$MR_REPO/$dir" ]; then
904 flagfile="$MR_REPO/$dir/.mr_last$1"
908 if [ -z "$flagfile" ]; then
909 error "cannot determine flag filename"
911 perl -wle 'print -f shift() ? int((-M _) * 24) : 9999' "$flagfile"
916 if [ -d "$MR_REPO"/.svn ]; then
918 elif [ -d "$MR_REPO"/.git ]; then
920 git pull -t origin master
924 elif [ -d "$MR_REPO"/.bzr ]; then
926 elif [ -d "$MR_REPO"/CVS ]; then
928 elif [ -d "$MR_REPO"/.hg ]; then
929 hg pull "$@" && hg update "$@"
931 error "unknown repo type"
934 if [ -d "$MR_REPO"/.svn ]; then
936 elif [ -d "$MR_REPO"/.git ]; then
937 git status "$@" || true
938 elif [ -d "$MR_REPO"/.bzr ]; then
940 elif [ -d "$MR_REPO"/CVS ]; then
942 elif [ -d "$MR_REPO"/.hg ]; then
945 error "unknown repo type"
948 if [ -d "$MR_REPO"/.svn ]; then
950 elif [ -d "$MR_REPO"/.git ]; then
951 git commit -a "$@" && git push --all
952 elif [ -d "$MR_REPO"/.bzr ]; then
953 bzr commit "$@" && bzr push
954 elif [ -d "$MR_REPO"/CVS ]; then
956 elif [ -d "$MR_REPO"/.hg ]; then
957 hg commit -m "$@" && hg push
959 error "unknown repo type"
962 if [ -d "$MR_REPO"/.svn ]; then
964 elif [ -d "$MR_REPO"/.git ]; then
966 elif [ -d "$MR_REPO"/.bzr ]; then
968 elif [ -d "$MR_REPO"/CVS ]; then
970 elif [ -d "$MR_REPO"/.hg ]; then
973 error "unknown repo type"
976 if [ -d "$MR_REPO"/.svn ]; then
978 elif [ -d "$MR_REPO"/.git ]; then
980 elif [ -d "$MR_REPO"/.bzr ]; then
982 elif [ -d "$MR_REPO"/CVS ]; then
984 elif [ -d "$MR_REPO"/.hg ]; then
987 error "unknown repo type"
993 basedir="$(basename $(pwd))"
995 url=$(LANG=C svn info . | grep -i ^URL: | cut -d ' ' -f 2)
996 if [ -z "$url" ]; then
997 error "cannot determine svn url"
999 echo "Registering svn url: $url in $MR_CONFIG"
1000 mr -c "$MR_CONFIG" config "$(pwd)" checkout="svn co $url $basedir"
1001 elif [ -d .git ]; then
1002 url=$(LANG=C git-config --get remote.origin.url)
1003 if [ -z "$url" ]; then
1004 error "cannot determine git url"
1006 echo "Registering git url: $url in $MR_CONFIG"
1007 mr -c "$MR_CONFIG" config "$(pwd)" checkout="git clone $url $basedir"
1008 elif [ -d .bzr ]; then
1009 url=$(cat .bzr/branch/parent)
1010 if [ -z "$url" ]; then
1011 error "cannot determine bzr url"
1013 echo "Registering bzr url: $url in $MR_CONFIG"
1014 mr -c "$MR_CONFIG" config "$(pwd)" checkout="bzr clone $url $basedir"
1015 elif [ -d CVS ]; then
1016 repo=$(cat CVS/Repository)
1017 root=$(cat CVS/Root)
1018 if [ -z "$root" ]; then
1019 error "cannot determine cvs root"
1021 echo "Registering cvs repository $repo at root $root"
1022 mr -c "$MR_CONFIG" config "$(pwd)" \
1023 checkout="cvs -d '$root' co -d $basedir $repo"
1024 elif [ -d .hg ]; then
1025 url=$(hg showconfig paths.default)
1026 echo "Registering mercurial repo url: $url in $MR_CONFIG"
1027 mr -c "$MR_CONFIG" config "$(pwd)" \
1028 checkout="hg clone $url $basedir"
1030 error "unable to register this repo type"
1033 if [ ! -e "$MR_PATH" ]; then
1034 error "cannot find program path"
1036 (pod2man -c mr "$MR_PATH" | man -l -) || error "pod2man or man failed"
1040 ed = echo "A horse is a horse, of course, of course.."
1041 T = echo "I pity the fool."
1042 right = echo "Not found."