| 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 | git refs create [--message=<reason>] [--no-deref] [--create-reflog] <ref> <new-value> |
| 24 | git refs delete [--message=<reason>] [--no-deref] <ref> [<old-value>] |
| 25 | git refs update [--message=<reason>] [--no-deref] [--create-reflog] <ref> <new-value> [<old-value>] |
| 26 | git refs rename [--message=<reason>] <old-ref> <new-ref> |
| 27 | |
| 28 | DESCRIPTION |
| 29 | ----------- |
| 30 | |
| 31 | This command provides low-level access to refs. |
| 32 | |
| 33 | COMMANDS |
| 34 | -------- |
| 35 | |
| 36 | `migrate`:: |
| 37 | Migrate ref store between different formats. |
| 38 | |
| 39 | `verify`:: |
| 40 | Verify reference database consistency. |
| 41 | |
| 42 | list:: |
| 43 | List references in the repository with support for filtering, |
| 44 | formatting, and sorting. This subcommand is an alias for |
| 45 | linkgit:git-for-each-ref[1] and offers identical functionality. |
| 46 | |
| 47 | exists:: |
| 48 | Check whether the given reference exists. Returns an exit code of 0 if |
| 49 | it does, 2 if it is missing, and 1 in case looking up the reference |
| 50 | failed with an error other than the reference being missing. This does |
| 51 | not verify whether the reference resolves to an actual object. |
| 52 | |
| 53 | optimize:: |
| 54 | Optimizes references to improve repository performance and reduce disk |
| 55 | usage. This subcommand is an alias for linkgit:git-pack-refs[1] and |
| 56 | offers identical functionality. |
| 57 | |
| 58 | create:: |
| 59 | Create the given reference, which must not already exist, pointing at |
| 60 | `<new-value>`. |
| 61 | |
| 62 | delete:: |
| 63 | Delete the given reference. This subcommand mirrors `git update-ref -d` |
| 64 | (see linkgit:git-update-ref[1]). When `<old-value>` is given, the |
| 65 | reference is only deleted after verifying that it currently contains |
| 66 | `<old-value>`. |
| 67 | |
| 68 | update:: |
| 69 | Update the given reference to point at `<new-value>`. If `<old-value>` |
| 70 | is given, the reference is only updated after verifying that it |
| 71 | currently contains `<old-value>`. As a special case, an all-zeroes |
| 72 | `<new-value>` deletes the branch, whereas an all-zeroes `<old-value>` |
| 73 | ensures that the branch does not yet exist. |
| 74 | |
| 75 | rename:: |
| 76 | Rename the reference `<oldref>` to `<newref>`. The old reference must |
| 77 | exist and the new reference must not yet exist, and both must have a |
| 78 | well-formed name (see linkgit:git-check-ref-format[1]). |
| 79 | |
| 80 | OPTIONS |
| 81 | ------- |
| 82 | |
| 83 | The following options are specific to `git refs migrate`: |
| 84 | |
| 85 | `--ref-format=<format>`:: |
| 86 | The ref format to migrate the ref store to. Can be one of: |
| 87 | + |
| 88 | include::ref-storage-format.adoc[] |
| 89 | |
| 90 | `--dry-run`:: |
| 91 | Perform the migration, but do not modify the repository. The migrated |
| 92 | refs will be written into a separate directory that can be inspected |
| 93 | separately. The name of the directory will be reported on stdout. This |
| 94 | can be used to double check that the migration works as expected before |
| 95 | performing the actual migration. |
| 96 | |
| 97 | `--reflog`:: |
| 98 | `--no-reflog`:: |
| 99 | Choose between migrating the reflog data to the new backend, |
| 100 | and discarding them. The default is "--reflog", to migrate. |
| 101 | |
| 102 | The following options are specific to `git refs verify`: |
| 103 | |
| 104 | `--strict`:: |
| 105 | Enable stricter error checking. This will cause warnings to be |
| 106 | reported as errors. See linkgit:git-fsck[1]. |
| 107 | |
| 108 | `--verbose`:: |
| 109 | When verifying the reference database consistency, be chatty. |
| 110 | |
| 111 | The following options are specific to 'git refs list': |
| 112 | |
| 113 | include::for-each-ref-options.adoc[] |
| 114 | |
| 115 | The following options are specific to 'git refs optimize': |
| 116 | |
| 117 | include::pack-refs-options.adoc[] |
| 118 | |
| 119 | The following options are specific to commands which write references: |
| 120 | |
| 121 | `--create-reflog`:: |
| 122 | Create a reflog for the reference even if one would not ordinarily be |
| 123 | created. |
| 124 | |
| 125 | `--message=<reason>`:: |
| 126 | Use the given <reason> string for the reflog entry associated with the |
| 127 | update. An empty message is rejected. |
| 128 | |
| 129 | `--no-deref`:: |
| 130 | Operate on <ref> itself rather than the reference it points to via a |
| 131 | symbolic ref. |
| 132 | |
| 133 | KNOWN LIMITATIONS |
| 134 | ----------------- |
| 135 | |
| 136 | The ref format migration has several known limitations in its current form: |
| 137 | |
| 138 | * It is not possible to migrate repositories that have worktrees. |
| 139 | |
| 140 | * There is no way to block concurrent writes to the repository during an |
| 141 | ongoing migration. Concurrent writes can lead to an inconsistent migrated |
| 142 | state. Users are expected to block writes on a higher level. If your |
| 143 | repository is registered for scheduled maintenance, it is recommended to |
| 144 | unregister it first with git-maintenance(1). |
| 145 | |
| 146 | These limitations may eventually be lifted. |
| 147 | |
| 148 | GIT |
| 149 | --- |
| 150 | Part of the linkgit:git[1] suite |