Load extension:

  $ echo "[extensions]" >> $HGRCPATH
  $ echo "onsub = $TESTDIR/onsub.py" >> $HGRCPATH

Check help formatting:

  $ hg help onsub
  hg onsub [-b] [-0] [--ignore-errors] CMD
  
  execute a command in each subrepository
  
      Executes CMD with the current working directory set to the root of each
      subrepository. By default, execution stops if CMD returns a non-zero exit
      code. Use --ignore-errors to override this.
  
      Use --verbose/-v to print the command being run and the subrepo name for
      each run of CMD in a subrepo. Alternately, use --print0/-0 to print just
      the subrepo name followed by a NUL character instead of a newline. This
      can be useful in combination with "hg status --print0".
  
      The command has access to the following environment variables:
  
      "HG_REPO":
          Absolute path to the top-level repository in which the onsub command
          was executed.
  
      "HG_SUBPATH":
          Relative path to the current subrepository from the top-level
          repository.
  
      "HG_SUBURL":
          URL for the current subrepository as specified in the containing
          repository's ".hgsub" file.
  
      "HG_SUBSTATE":
          State of the current subrepository as specified in the containing
          repository's ".hgsubstate" file.
  
  options:
  
   -b --breadth-first  use breadth-first traversal
      --max-depth N    limit recursion to N levels (negative for no limit)
                       (default: -1)
      --ignore-errors  continue execution despite errors
   -0 --print0         end subrepository names with NUL, for use with xargs
  
  use "hg -v help onsub" to show global options

Create some nicely nested subrepositories:

  $ hg init
  $ for d in a b; do hg init $d; echo "$d = $d" >> .hgsub; done
  $ hg add .hgsub

  $ cd a

  $ for d in x y; do hg init $d; echo "$d = $d" >> .hgsub; done
  $ hg add .hgsub

  $ cd y
  $ for d in r s t; do hg init $d; echo "$d = $d" >> .hgsub; done
  $ hg add .hgsub
  $ cd ..

  $ cd ..

  $ cd b
  $ for d in u v; do hg init $d; echo "$d = $d" >> .hgsub; done
  $ hg add .hgsub
  $ cd ..

  $ hg commit -m init -S
  committing subrepository a
  committing subrepository a/x
  committing subrepository a/y
  committing subrepository a/y/r
  committing subrepository a/y/s
  committing subrepository a/y/t
  committing subrepository b
  committing subrepository b/u
  committing subrepository b/v

The default depth-first traversal:

  $ hg onsub 'echo $HG_SUBPATH'
  a
  a/x
  a/y
  a/y/r
  a/y/s
  a/y/t
  b
  b/u
  b/v

Breadth-first traversal:

  $ hg onsub 'echo $HG_SUBPATH' --breadth-first
  a
  b
  a/x
  a/y
  b/u
  b/v
  a/y/r
  a/y/s
  a/y/t

Limit depth of traversal:
  $ hg onsub --max-depth 1 'echo $HG_SUBPATH'
  a
  b
  $ hg onsub --max-depth 2 'echo $HG_SUBPATH'
  a
  a/x
  a/y
  b
  b/u
  b/v
  $ hg onsub --max-depth 2 -b 'echo $HG_SUBPATH'
  a
  b
  a/x
  a/y
  b/u
  b/v

Test aborting:

  $ hg onsub -v 'test $HG_SUBPATH != "a/y/r"'
  executing 'test $HG_SUBPATH != "a/y/r"' in a
  executing 'test $HG_SUBPATH != "a/y/r"' in a/x
  executing 'test $HG_SUBPATH != "a/y/r"' in a/y
  executing 'test $HG_SUBPATH != "a/y/r"' in a/y/r
  abort: terminated onsub in a/y/r: test exited with status 1
  [255]

Test aborting:

  $ hg onsub -v --ignore-errors false
  executing 'false' in a
  executing 'false' in a/x
  executing 'false' in a/y
  executing 'false' in a/y/r
  executing 'false' in a/y/s
  executing 'false' in a/y/t
  executing 'false' in b
  executing 'false' in b/u
  executing 'false' in b/v

Test --print0:

  $ mv a 'with spaces'
  $ echo 'with spaces = with spaces' > .hgsub
  $ echo 'b = b' >> .hgsub
  $ hg commit -m rename
  committing subrepository with spaces
  $ hg onsub -0 | xargs -n 1 -0
  b
  b/u
  b/v
  with spaces
  with spaces/x
  with spaces/y
  with spaces/y/r
  with spaces/y/s
  with spaces/y/t