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) {
580 $SIG{CHLD}='DEFAULT';
582 my $repo = shift @repos;
583 my $pid = open(my $fh, "-|");
585 open(STDERR, ">&STDOUT");
586 exit action($action, @$repo);
594 my ($rin, $rout) = ('','', '');
596 foreach my $x (@fhs) {
597 next unless defined $x;
598 vec($rin, fileno($x), 1) = 1;
600 $nfound = select($rout=$rin, undef, undef, 1);
601 foreach my $i (0..$#fhs) {
603 next unless defined $fh;
604 if (vec($rout, fileno($fh), 1) == 1) {
606 if (sysread($fh, $r, 1024) == 0) {
616 while (@fhs and !defined $fhs[0]) {
624 while ((my $pid = waitpid(-1, &WNOHANG)) > 0) {
625 record($jobs{$pid}, $? >> 8) if exists $jobs{$pid};
630 my $dir=shift()->[0];
636 elsif ($ret == FAILED) {
639 elsif ($ret == SKIPPED) {
642 elsif ($ret == ABORT) {
646 die "unknown exit status $ret";
655 return "$count ".($count > 1 ? $plural : $singular);
661 sub loadconfig { #{{{
668 if (ref $f eq 'GLOB') {
677 my $absf=abs_path($f);
678 if ($loaded{$absf}) {
683 ($dir)=$f=~/^(.*\/)[^\/]+$/;
684 if (! defined $dir) {
687 $dir=abs_path($dir)."/";
689 if (! exists $configfiles{$dir}) {
690 $configfiles{$dir}=$f;
693 # copy in defaults from first parent
695 while ($parent=~s/^(.*\/)[^\/]+\/?$/$1/) {
696 if ($parent eq '/') {
699 if (exists $config{$parent} &&
700 exists $config{$parent}{DEFAULT}) {
701 $config{$dir}{DEFAULT}={ %{$config{$parent}{DEFAULT}} };
706 print "mr: loading config $f\n" if $verbose;
707 open($in, "<", $f) || die "mr: open $f: $!\n";
718 next if /^\s*\#/ || /^\s*$/;
719 if (/^\[([^\]]*)\]\s*$/) {
722 elsif (/^(\w+)\s*=\s*(.*)/) {
727 while (@lines && $lines[0]=~/^\s(.+)/) {
734 if (! defined $section) {
735 die "$f line $.: parameter ($parameter) not in section\n";
737 if ($section ne 'ALIAS' &&
738 ! exists $config{$dir}{$section} &&
739 exists $config{$dir}{DEFAULT}) {
741 $config{$dir}{$section}={ %{$config{$dir}{DEFAULT}} };
743 if ($section eq 'ALIAS') {
744 $alias{$parameter}=$value;
746 elsif ($parameter eq 'lib') {
747 $config{$dir}{$section}{lib}.=$value."\n";
750 $config{$dir}{$section}{$parameter}=$value;
751 $knownactions{$parameter}=1;
752 if ($parameter eq 'chain' &&
753 length $dir && $section ne "DEFAULT" &&
754 -e $dir.$section."/.mrconfig") {
755 my $ret=system($value);
757 if (($? & 127) == 2) {
758 print STDERR "mr $action: chain test interrupted\n";
762 print STDERR "mr $action: chain test received signal ".($? & 127)."\n";
766 push @toload, $dir.$section."/.mrconfig";
772 die "$f line $line: parse error\n";
781 sub modifyconfig { #{{{
783 # the section to modify or add
784 my $targetsection=shift;
785 # fields to change in the section
786 # To remove a field, set its value to "".
793 open(my $in, "<", $f) || die "mr: open $f: $!\n";
798 my $formatfield=sub {
800 my @value=split(/\n/, shift);
802 return "$field = ".shift(@value)."\n".
803 join("", map { "\t$_\n" } @value);
807 while ($out[$#out] =~ /^\s*$/) {
808 unshift @blanks, pop @out;
810 foreach my $field (sort keys %changefields) {
811 if (length $changefields{$field}) {
812 push @out, "$field = $changefields{$field}\n";
813 delete $changefields{$field};
823 if (/^\s*\#/ || /^\s*$/) {
826 elsif (/^\[([^\]]*)\]\s*$/) {
827 if (defined $section &&
828 $section eq $targetsection) {
836 elsif (/^(\w+)\s*=\s(.*)/) {
841 while (@lines && $lines[0]=~/^\s(.+)/) {
847 if ($section eq $targetsection) {
848 if (exists $changefields{$parameter}) {
849 if (length $changefields{$parameter}) {
850 $value=$changefields{$parameter};
852 delete $changefields{$parameter};
856 push @out, $formatfield->($parameter, $value);
860 if (defined $section &&
861 $section eq $targetsection) {
864 elsif (%changefields) {
865 push @out, "\n[$targetsection]\n";
866 foreach my $field (sort keys %changefields) {
867 if (length $changefields{$field}) {
868 push @out, $formatfield->($field, $changefields{$field});
873 open(my $out, ">", $f) || die "mr: write $f: $!\n";
878 # Finally, some useful actions that mr knows about by default.
879 # These can be overridden in ~/.mrconfig.
894 for dir in .git .svn .bzr CVS .hg; do
895 if [ -e "$MR_REPO/$dir" ]; then
896 flagfile="$MR_REPO/$dir/.mr_last$1"
900 if [ -z "$flagfile" ]; then
901 error "cannot determine flag filename"
903 perl -wle 'print -f shift() ? int((-M _) * 24) : 9999' "$flagfile"
908 if [ -d "$MR_REPO"/.svn ]; then
910 elif [ -d "$MR_REPO"/.git ]; then
912 git pull -t origin master
916 elif [ -d "$MR_REPO"/.bzr ]; then
918 elif [ -d "$MR_REPO"/CVS ]; then
920 elif [ -d "$MR_REPO"/.hg ]; then
921 hg pull "$@" && hg update "$@"
923 error "unknown repo type"
926 if [ -d "$MR_REPO"/.svn ]; then
928 elif [ -d "$MR_REPO"/.git ]; then
929 git status "$@" || true
930 elif [ -d "$MR_REPO"/.bzr ]; then
932 elif [ -d "$MR_REPO"/CVS ]; then
934 elif [ -d "$MR_REPO"/.hg ]; then
937 error "unknown repo type"
940 if [ -d "$MR_REPO"/.svn ]; then
942 elif [ -d "$MR_REPO"/.git ]; then
943 git commit -a "$@" && git push --all
944 elif [ -d "$MR_REPO"/.bzr ]; then
945 bzr commit "$@" && bzr push
946 elif [ -d "$MR_REPO"/CVS ]; then
948 elif [ -d "$MR_REPO"/.hg ]; then
949 hg commit -m "$@" && hg push
951 error "unknown repo type"
954 if [ -d "$MR_REPO"/.svn ]; then
956 elif [ -d "$MR_REPO"/.git ]; then
958 elif [ -d "$MR_REPO"/.bzr ]; then
960 elif [ -d "$MR_REPO"/CVS ]; then
962 elif [ -d "$MR_REPO"/.hg ]; then
965 error "unknown repo type"
968 if [ -d "$MR_REPO"/.svn ]; then
970 elif [ -d "$MR_REPO"/.git ]; then
972 elif [ -d "$MR_REPO"/.bzr ]; then
974 elif [ -d "$MR_REPO"/CVS ]; then
976 elif [ -d "$MR_REPO"/.hg ]; then
979 error "unknown repo type"
985 basedir="$(basename $(pwd))"
987 url=$(LANG=C svn info . | grep -i ^URL: | cut -d ' ' -f 2)
988 if [ -z "$url" ]; then
989 error "cannot determine svn url"
991 echo "Registering svn url: $url in $MR_CONFIG"
992 mr -c "$MR_CONFIG" config "$(pwd)" checkout="svn co $url $basedir"
993 elif [ -d .git ]; then
994 url=$(LANG=C git-config --get remote.origin.url)
995 if [ -z "$url" ]; then
996 error "cannot determine git url"
998 echo "Registering git url: $url in $MR_CONFIG"
999 mr -c "$MR_CONFIG" config "$(pwd)" checkout="git clone $url $basedir"
1000 elif [ -d .bzr ]; then
1001 url=$(cat .bzr/branch/parent)
1002 if [ -z "$url" ]; then
1003 error "cannot determine bzr url"
1005 echo "Registering bzr url: $url in $MR_CONFIG"
1006 mr -c "$MR_CONFIG" config "$(pwd)" checkout="bzr clone $url $basedir"
1007 elif [ -d CVS ]; then
1008 repo=$(cat CVS/Repository)
1009 root=$(cat CVS/Root)
1010 if [ -z "$root" ]; then
1011 error "cannot determine cvs root"
1013 echo "Registering cvs repository $repo at root $root"
1014 mr -c "$MR_CONFIG" config "$(pwd)" \
1015 checkout="cvs -d '$root' co -d $basedir $repo"
1016 elif [ -d .hg ]; then
1017 url=$(hg showconfig paths.default)
1018 echo "Registering mercurial repo url: $url in $MR_CONFIG"
1019 mr -c "$MR_CONFIG" config "$(pwd)" \
1020 checkout="hg clone $url $basedir"
1022 error "unable to register this repo type"
1025 if [ ! -e "$MR_PATH" ]; then
1026 error "cannot find program path"
1028 (pod2man -c mr "$MR_PATH" | man -l -) || error "pod2man or man failed"
1032 ed = echo "A horse is a horse, of course, of course.."
1033 T = echo "I pity the fool."
1034 right = echo "Not found."