]>
Commit | Line | Data |
---|---|---|
d28f7cb9 JH |
1 | git-pack-refs(1) |
2 | ================ | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-pack-refs - Pack heads and tags for efficient repository access | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
7791a1d9 | 10 | [verse] |
6dcffc68 | 11 | 'git pack-refs' [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>] |
d28f7cb9 JH |
12 | |
13 | DESCRIPTION | |
14 | ----------- | |
15 | ||
16 | Traditionally, tips of branches and tags (collectively known as | |
831e61f8 JH |
17 | 'refs') were stored one file per ref in a (sub)directory |
18 | under `$GIT_DIR/refs` | |
d28f7cb9 JH |
19 | directory. While many branch tips tend to be updated often, |
20 | most tags and some branch tips are never updated. When a | |
21 | repository has hundreds or thousands of tags, this | |
22 | one-file-per-ref format both wastes storage and hurts | |
23 | performance. | |
24 | ||
25 | This command is used to solve the storage and performance | |
831e61f8 | 26 | problem by storing the refs in a single file, |
d28f7cb9 | 27 | `$GIT_DIR/packed-refs`. When a ref is missing from the |
831e61f8 JH |
28 | traditional `$GIT_DIR/refs` directory hierarchy, it is looked |
29 | up in this | |
d28f7cb9 JH |
30 | file and used if found. |
31 | ||
38b7ccbe | 32 | Subsequent updates to branches always create new files under |
831e61f8 | 33 | `$GIT_DIR/refs` directory hierarchy. |
d28f7cb9 | 34 | |
af67e91c | 35 | A recommended practice to deal with a repository with too many |
4a81bfa1 JM |
36 | refs is to pack its refs with `--all` once, and |
37 | occasionally run `git pack-refs`. Tags are by | |
af67e91c JH |
38 | definition stationary and are not expected to change. Branch |
39 | heads will be packed with the initial `pack-refs --all`, but | |
40 | only the currently active branch heads will become unpacked, | |
38b7ccbe | 41 | and the next `pack-refs` (without `--all`) will leave them |
af67e91c JH |
42 | unpacked. |
43 | ||
44 | ||
d28f7cb9 JH |
45 | OPTIONS |
46 | ------- | |
47 | ||
3240240f | 48 | --all:: |
d28f7cb9 | 49 | |
af67e91c JH |
50 | The command by default packs all tags and refs that are already |
51 | packed, and leaves other refs | |
d28f7cb9 JH |
52 | alone. This is because branches are expected to be actively |
53 | developed and packing their tips does not help performance. | |
283174b2 JC |
54 | This option causes all refs to be packed as well, with the exception |
55 | of hidden refs, broken refs, and symbolic refs. Useful for a repository | |
56 | with many branches of historical interests. | |
d28f7cb9 | 57 | |
3240240f | 58 | --no-prune:: |
0f018bab JH |
59 | |
60 | The command usually removes loose refs under `$GIT_DIR/refs` | |
61 | hierarchy after packing them. This option tells it not to. | |
d28f7cb9 | 62 | |
6dcffc68 PS |
63 | --auto:: |
64 | ||
65 | Pack refs as needed depending on the current state of the ref database. The | |
66 | behavior depends on the ref format used by the repository and may change in the | |
67 | future. | |
68 | + | |
69 | - "files": No special handling for `--auto` has been implemented. | |
70 | + | |
71 | - "reftable": Tables are compacted such that they form a geometric | |
72 | sequence. For two tables N and N+1, where N+1 is newer, this | |
73 | maintains the property that N is at least twice as big as N+1. Only | |
74 | tables that violate this property are compacted. | |
75 | ||
4fe42f32 JC |
76 | --include <pattern>:: |
77 | ||
78 | Pack refs based on a `glob(7)` pattern. Repetitions of this option | |
79 | accumulate inclusion patterns. If a ref is both included in `--include` and | |
80 | `--exclude`, `--exclude` takes precedence. Using `--include` will preclude all | |
81 | tags from being included by default. Symbolic refs and broken refs will never | |
82 | be packed. When used with `--all`, it will be a noop. Use `--no-include` to clear | |
83 | and reset the list of patterns. | |
84 | ||
826ae79f JC |
85 | --exclude <pattern>:: |
86 | ||
87 | Do not pack refs matching the given `glob(7)` pattern. Repetitions of this option | |
88 | accumulate exclusion patterns. Use `--no-exclude` to clear and reset the list of | |
89 | patterns. If a ref is already packed, including it with `--exclude` will not | |
90 | unpack it. | |
91 | ||
92 | When used with `--all`, pack only loose refs which do not match any of | |
93 | the provided `--exclude` patterns. | |
94 | ||
4fe42f32 JC |
95 | When used with `--include`, refs provided to `--include`, minus refs that are |
96 | provided to `--exclude` will be packed. | |
97 | ||
831e61f8 JH |
98 | |
99 | BUGS | |
100 | ---- | |
101 | ||
102 | Older documentation written before the packed-refs mechanism was | |
103 | introduced may still say things like ".git/refs/heads/<branch> file | |
104 | exists" when it means "branch <branch> exists". | |
105 | ||
106 | ||
d28f7cb9 JH |
107 | GIT |
108 | --- | |
9e1f0a85 | 109 | Part of the linkgit:git[1] suite |