| 1 | git-refs(1) |
| 2 | =========== |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-refs - Low-level access to refs |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [synopsis] |
| 12 | git refs migrate --ref-format=<format> [--no-reflog] [--dry-run] |
| 13 | git refs verify [--strict] [--verbose] |
| 14 | git refs list [--count=<count>] [--shell|--perl|--python|--tcl] |
| 15 | [(--sort=<key>)...] [--format=<format>] |
| 16 | [--include-root-refs] [--points-at=<object>] |
| 17 | [--merged[=<object>]] [--no-merged[=<object>]] |
| 18 | [--contains[=<object>]] [--no-contains[=<object>]] |
| 19 | [(--exclude=<pattern>)...] [--start-after=<marker>] |
| 20 | [ --stdin | (<pattern>...)] |
| 21 | git refs exists <ref> |
| 22 | git refs optimize [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>] |
| 23 | |
| 24 | DESCRIPTION |
| 25 | ----------- |
| 26 | |
| 27 | This command provides low-level access to refs. |
| 28 | |
| 29 | COMMANDS |
| 30 | -------- |
| 31 | |
| 32 | `migrate`:: |
| 33 | Migrate ref store between different formats. |
| 34 | |
| 35 | `verify`:: |
| 36 | Verify reference database consistency. |
| 37 | |
| 38 | list:: |
| 39 | List references in the repository with support for filtering, |
| 40 | formatting, and sorting. This subcommand is an alias for |
| 41 | linkgit:git-for-each-ref[1] and offers identical functionality. |
| 42 | |
| 43 | exists:: |
| 44 | Check whether the given reference exists. Returns an exit code of 0 if |
| 45 | it does, 2 if it is missing, and 1 in case looking up the reference |
| 46 | failed with an error other than the reference being missing. This does |
| 47 | not verify whether the reference resolves to an actual object. |
| 48 | |
| 49 | optimize:: |
| 50 | Optimizes references to improve repository performance and reduce disk |
| 51 | usage. This subcommand is an alias for linkgit:git-pack-refs[1] and |
| 52 | offers identical functionality. |
| 53 | |
| 54 | OPTIONS |
| 55 | ------- |
| 56 | |
| 57 | The following options are specific to `git refs migrate`: |
| 58 | |
| 59 | `--ref-format=<format>`:: |
| 60 | The ref format to migrate the ref store to. Can be one of: |
| 61 | + |
| 62 | include::ref-storage-format.adoc[] |
| 63 | |
| 64 | `--dry-run`:: |
| 65 | Perform the migration, but do not modify the repository. The migrated |
| 66 | refs will be written into a separate directory that can be inspected |
| 67 | separately. The name of the directory will be reported on stdout. This |
| 68 | can be used to double check that the migration works as expected before |
| 69 | performing the actual migration. |
| 70 | |
| 71 | `--reflog`:: |
| 72 | `--no-reflog`:: |
| 73 | Choose between migrating the reflog data to the new backend, |
| 74 | and discarding them. The default is "--reflog", to migrate. |
| 75 | |
| 76 | The following options are specific to `git refs verify`: |
| 77 | |
| 78 | `--strict`:: |
| 79 | Enable stricter error checking. This will cause warnings to be |
| 80 | reported as errors. See linkgit:git-fsck[1]. |
| 81 | |
| 82 | `--verbose`:: |
| 83 | When verifying the reference database consistency, be chatty. |
| 84 | |
| 85 | The following options are specific to 'git refs list': |
| 86 | |
| 87 | include::for-each-ref-options.adoc[] |
| 88 | |
| 89 | The following options are specific to 'git refs optimize': |
| 90 | |
| 91 | include::pack-refs-options.adoc[] |
| 92 | |
| 93 | KNOWN LIMITATIONS |
| 94 | ----------------- |
| 95 | |
| 96 | The ref format migration has several known limitations in its current form: |
| 97 | |
| 98 | * It is not possible to migrate repositories that have worktrees. |
| 99 | |
| 100 | * There is no way to block concurrent writes to the repository during an |
| 101 | ongoing migration. Concurrent writes can lead to an inconsistent migrated |
| 102 | state. Users are expected to block writes on a higher level. If your |
| 103 | repository is registered for scheduled maintenance, it is recommended to |
| 104 | unregister it first with git-maintenance(1). |
| 105 | |
| 106 | These limitations may eventually be lifted. |
| 107 | |
| 108 | GIT |
| 109 | --- |
| 110 | Part of the linkgit:git[1] suite |