src/list_packs.txt

   1 Usage: list_packs [-C <dir>] [option ...] ( --only <file> | <directory> )
   2
   3   -C <dir>             change current working director to <dir> before anything
   4   --quiet              no error messages but exit code still set
   5   --all                inspect all *.pack instead of just pack-<sha1>*.pack
   6   --exclude-keep       exclude any matching packs with associated .keep
   7   --exclude-no-keep    exclude any matching packs without associated .keep
   8   --exclude-bitmap     exclude any matching packs with associated .bitmap
   9   --exclude-no-bitmap  exclude any matching packs without associated .bitmap
  10   --exclude-bndl       exclude any matching packs with associated .bndl
  11   --exclude-no-bndl    exclude any matching packs without associated .bndl
  12   --exclude-idx        exclude any matching packs with associated .idx
  13   --exclude-no-idx     exclude any matching packs without associated .idx
  14   --exclude-ext <ext>  exclude any matching packs with associated .ext
  15   --exclude-no-ext <e> exclude any matching packs without associated .e
  16   --exclude-sfx <sfx>  exclude any matching packs with names matching *sfx.ext
  17   --exclude-no-sfx <s> exclude any matching packs without names matching *s.ext
  18   --exclude-limit <n>  exclude any matching packs with at least n objects
  19                        if n is < 0 then exclude packs without at least -n objs
  20   --object-limit <n>   sort matches in ascending (descending if n < 0) order of
  21                        obj count and include packs while total obj count <= n
  22   --include-boundary   include the boundary pack that exceeds --object-limit
  23   --max-matches <n>    limit final output to the first n matches (at most)
  24   --count              instead of pack files output a count of them
  25   --count-objects      instead of pack files output a total object count
  26
  27   --only <file>        inspect only packs named in <file> (use - for stdin)
  28   <directory>          inspect only .pack files in here (see the --all option)
  29
  30   If multiple -C options are given they are processed in the order given and
  31     they are always processed before attempting to open <directory> or <file>.
  32
  33   If a <directory> is given then the --only option may NOT be used.
  34
  35   If the --only option is used then neither --all nor <directory> may be used.
  36
  37   If both --count and --count-objects are given, the last one wins.
  38
  39   If both --exclude-xxx and --exclude-no-xxx are given, then the last one wins.
  40
  41   If neither --exclude-xxx nor --exclude-no-xxx is given, then packs both with
  42     AND without an associated .xxx file match.
  43
  44   The --exclude-ext and --exclude-no-ext options require the given <ext> to
  45     contain no whitespace, ':', '/', '\\' or '.' characters and be no more than
  46     ten characters long.
  47
  48   The --exclude-sfx and --exclude-no-sfx options require the given <sfx> to
  49     contain no whitespace, ':', '/', '\\' or '.' characters, be no more than
  50     11 characters long and start with a non hexadecimal character (e.g. _r).
  51     With multiple --exclude-no-sfx options they operate as "or" conditions.
  52     (e.g. "--exclude-no-sfx _u --exclude-no-sfx _r" matches _u "or" _r names)
  53
  54   If --object-limit is given, all other options are first applied as normal,
  55     but the matching packs are collected in a list which is then sorted in
  56     ascending order (descending order if object limit is negative) by the
  57     number of objects in the pack.  Then the list is walked in sorted order
  58     and the total object count computed along the way.  The first pack that
  59     has an object count that causes the total object count so far to EXCEED
  60     the absolute value of the object limit is excluded as well as all
  61     following packs.  However, if --include-boundary is given then the pack
  62     that causes the total object count so far to EXCEED the absolute value of
  63     the object limit will be INCLUDED while all following packs are excluded.
  64     Processing then continues as though only the non-excluded packs matched
  65     meaning final output can still be a count of packs, count of total objects
  66     or list of pack file names depending on the options given.
  67
  68   If --max-matches is given, then after ALL other matching has been performed
  69     only the first n matches (when there are more than n total final matches)
  70     participate in generating the final output.
  71
  72   For --only, pack names are relative to the current directory (but see the -C
  73     option) and MUST include the trailing .pack and MUST be one per line but
  74     any characters after and including the first whitespace or colon character
  75     are ignored on each line.  Empty lines and lines with the first char
  76     whitespace or ':' are ignored.
  77
  78   The --only option will properly read a fast-import --export-pack-edges file.
  79
  80   If an error (other than EOF) occurs while reading the --only file, an error
  81     message will be output (unless the --quiet option is used) and the exit
  82     status will be non-zero.
  83
  84   Output is one pack file name (including the .pack suffix) per line unless
  85     the --count or --count-objects option is used in which case it's a single
  86     decimal count of either the number of pack file names that would have been
  87     output (--count) or the total count of all the objects in all the pack
  88     files that would have been included in the output (--count-objects).
  89
  90   Using the --only option allows files not ending in .pack to be inspected in
  91     which case the --exclude-[no-]xxx options may not work as intended (since
  92     when there is no .pack suffix to remove they will just append the test
  93     suffix without first removing anything).
  94
  95   The --exclude-no-idx option not only checks for the existence of an
  96     associated .idx file, it also verifies the length is at least
  97     1072 + 28 * number of objects in the corresponding .pack file.  However,
  98     it does NOT validate the actual .idx file contents in any way (i.e.
  99     no signature check nor matching object count check).
 100
 101   If an otherwise matching .pack file fails the header sanity check test (it
 102     must have a PACK signature, a version of 2 or 3 and a length of at least
 103     32 + number of objects) or, when --exclude-no-idx is used and the
 104     associated .idx file fails the length check, a message is output to stderr
 105     unless the --quiet option is used.  Using --exclude-no-idx does NOT produce
 106     any error message when there is no associated .idx file, the .pack is just
 107     ignored.
 108
 109   If a file being checked is not actually a file (i.e. a directory or other
 110     non-file), an error message will be output unless the --quiet option is
 111     used.  However, operation then continues as though the non-file did not
 112     exist.