refs/refs-internal.h: new header file
There are a number of constants, structs, and static functions defined in refs.c and treated as private to the references module. But we want to support multiple reference backends within the reference module, and those backends will need access to some heretofore private declarations. We don't want those declarations to be visible to non-refs code, so we don't want to move them to refs.h. Instead, add a new header file, refs/refs-internal.h, that is intended to be included only from within the refs module. Make some functions non-static and move some declarations (and their corresponding docstrings) from refs.c to this file. In a moment we will add more content to the "refs" subdirectory. Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Signed-off-by: Jeff King <peff@peff.net>
Michael Haggerty committed
Nov 10, 2015 at 12:42 UTC
4cb77009e1fa692e56048754e2032ed044f28c26
2 files changed
+189
-165
refs.c
+9
-165
@@ -1,6 +1,7 @@
1
#include "cache.h"
2
#include "lockfile.h"
3
#include "refs.h"
4
+#include "refs/refs-internal.h"
5
#include "object.h"
6
#include "tag.h"
7
#include "dir.h"
@@ -34,41 +35,6 @@ static unsigned char refname_disposition[256] = {
35
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 0, 0, 4, 4
36
};
37
37
-/*
38
- * Flag passed to lock_ref_sha1_basic() telling it to tolerate broken
39
- * refs (i.e., because the reference is about to be deleted anyway).
40
- */
41
-#define REF_DELETING 0x02
42
-
43
-/*
44
- * Used as a flag in ref_update::flags when a loose ref is being
45
- * pruned.
46
- */
47
-#define REF_ISPRUNING 0x04
48
-
49
-/*
50
- * Used as a flag in ref_update::flags when the reference should be
51
- * updated to new_sha1.
52
- */
53
-#define REF_HAVE_NEW 0x08
54
-
55
-/*
56
- * Used as a flag in ref_update::flags when old_sha1 should be
57
- * checked.
58
- */
59
-#define REF_HAVE_OLD 0x10
60
-
61
-/*
62
- * Used as a flag in ref_update::flags when the lockfile needs to be
63
- * committed.
64
- */
65
-#define REF_NEEDS_COMMIT 0x20
66
-
67
-/*
68
- * 0x40 is REF_FORCE_CREATE_REFLOG, so skip it if you're adding a
69
- * value to ref_update::flags
70
- */
71
-
38
/*
39
* Try to read one refname component from the front of refname.
40
* Return the length of the component found, or -1 if the component is
@@ -340,20 +306,7 @@ static struct ref_dir *get_ref_dir(struct ref_entry *entry)
306
return dir;
307
}
308
343
-/*
344
- * Return true iff refname is minimally safe. "Safe" here means that
345
- * deleting a loose reference by this name will not do any damage, for
346
- * example by causing a file that is not a reference to be deleted.
347
- * This function does not check that the reference name is legal; for
348
- * that, use check_refname_format().
349
- *
350
- * We consider a refname that starts with "refs/" to be safe as long
351
- * as any ".." components that it might contain do not escape "refs/".
352
- * Names that do not start with "refs/" are considered safe iff they
353
- * consist entirely of upper case characters and '_' (like "HEAD" and
354
- * "MERGE_HEAD" but not "config" or "FOO/BAR").
355
- */
356
-static int refname_is_safe(const char *refname)
309
+int refname_is_safe(const char *refname)
310
{
311
if (starts_with(refname, "refs/")) {
312
char *buf;
@@ -1823,39 +1776,7 @@ static int filter_refs(const char *refname, const struct object_id *oid,
1776
return filter->fn(refname, oid, flags, filter->cb_data);
1777
}
1778
1826
-enum peel_status {
1827
- /* object was peeled successfully: */
1828
- PEEL_PEELED = 0,
1829
-
1830
- /*
1831
- * object cannot be peeled because the named object (or an
1832
- * object referred to by a tag in the peel chain), does not
1833
- * exist.
1834
- */
1835
- PEEL_INVALID = -1,
1836
-
1837
- /* object cannot be peeled because it is not a tag: */
1838
- PEEL_NON_TAG = -2,
1839
-
1840
- /* ref_entry contains no peeled value because it is a symref: */
1841
- PEEL_IS_SYMREF = -3,
1842
-
1843
- /*
1844
- * ref_entry cannot be peeled because it is broken (i.e., the
1845
- * symbolic reference cannot even be resolved to an object
1846
- * name):
1847
- */
1848
- PEEL_BROKEN = -4
1849
-};
1850
-
1851
-/*
1852
- * Peel the named object; i.e., if the object is a tag, resolve the
1853
- * tag recursively until a non-tag is found. If successful, store the
1854
- * result to sha1 and return PEEL_PEELED. If the object is not a tag
1855
- * or is not valid, return PEEL_NON_TAG or PEEL_INVALID, respectively,
1856
- * and leave sha1 unchanged.
1857
- */
1858
-static enum peel_status peel_object(const unsigned char *name, unsigned char *sha1)
1779
+enum peel_status peel_object(const unsigned char *name, unsigned char *sha1)
1780
{
1781
struct object *o = lookup_unknown_object(name);
1782
@@ -3110,27 +3031,10 @@ out:
3031
return ret;
3032
}
3033
3113
-/*
3114
- * Return 0 if a reference named refname could be created without
3115
- * conflicting with the name of an existing reference. Otherwise,
3116
- * return a negative value and write an explanation to err. If extras
3117
- * is non-NULL, it is a list of additional refnames with which refname
3118
- * is not allowed to conflict. If skip is non-NULL, ignore potential
3119
- * conflicts with refs in skip (e.g., because they are scheduled for
3120
- * deletion in the same operation). Behavior is undefined if the same
3121
- * name is listed in both extras and skip.
3122
- *
3123
- * Two reference names conflict if one of them exactly matches the
3124
- * leading components of the other; e.g., "foo/bar" conflicts with
3125
- * both "foo" and with "foo/bar/baz" but not with "foo/bar" or
3126
- * "foo/barbados".
3127
- *
3128
- * extras and skip must be sorted.
3129
- */
3130
-static int verify_refname_available(const char *newname,
3131
- struct string_list *extras,
3132
- struct string_list *skip,
3133
- struct strbuf *err)
3034
+int verify_refname_available(const char *newname,
3035
+ struct string_list *extras,
3036
+ struct string_list *skip,
3037
+ struct strbuf *err)
3038
{
3039
struct ref_dir *packed_refs = get_packed_refs(&ref_cache);
3040
struct ref_dir *loose_refs = get_loose_refs(&ref_cache);
@@ -3284,12 +3188,7 @@ static int commit_ref(struct ref_lock *lock)
3188
return 0;
3189
}
3190
3287
-/*
3288
- * copy the reflog message msg to buf, which has been allocated sufficiently
3289
- * large, while cleaning up the whitespaces. Especially, convert LF to space,
3290
- * because reflog file is one line per entry.
3291
- */
3292
-static int copy_reflog_msg(char *buf, const char *msg)
3191
+int copy_reflog_msg(char *buf, const char *msg)
3192
{
3193
char *cp = buf;
3194
char c;
@@ -3310,7 +3209,7 @@ static int copy_reflog_msg(char *buf, const char *msg)
3209
return cp - buf;
3210
}
3211
3313
-static int should_autocreate_reflog(const char *refname)
3212
+int should_autocreate_reflog(const char *refname)
3213
{
3214
if (!log_all_ref_updates)
3215
return 0;
@@ -3963,61 +3862,6 @@ int for_each_reflog(each_ref_fn fn, void *cb_data)
3862
return retval;
3863
}
3864
3966
-/**
3967
- * Information needed for a single ref update. Set new_sha1 to the new
3968
- * value or to null_sha1 to delete the ref. To check the old value
3969
- * while the ref is locked, set (flags & REF_HAVE_OLD) and set
3970
- * old_sha1 to the old value, or to null_sha1 to ensure the ref does
3971
- * not exist before update.
3972
- */
3973
-struct ref_update {
3974
- /*
3975
- * If (flags & REF_HAVE_NEW), set the reference to this value:
3976
- */
3977
- unsigned char new_sha1[20];
3978
- /*
3979
- * If (flags & REF_HAVE_OLD), check that the reference
3980
- * previously had this value:
3981
- */
3982
- unsigned char old_sha1[20];
3983
- /*
3984
- * One or more of REF_HAVE_NEW, REF_HAVE_OLD, REF_NODEREF,
3985
- * REF_DELETING, and REF_ISPRUNING:
3986
- */
3987
- unsigned int flags;
3988
- struct ref_lock *lock;
3989
- int type;
3990
- char *msg;
3991
- const char refname[FLEX_ARRAY];
3992
-};
3993
-
3994
-/*
3995
- * Transaction states.
3996
- * OPEN: The transaction is in a valid state and can accept new updates.
3997
- * An OPEN transaction can be committed.
3998
- * CLOSED: A closed transaction is no longer active and no other operations
3999
- * than free can be used on it in this state.
4000
- * A transaction can either become closed by successfully committing
4001
- * an active transaction or if there is a failure while building
4002
- * the transaction thus rendering it failed/inactive.
4003
- */
4004
-enum ref_transaction_state {
4005
- REF_TRANSACTION_OPEN = 0,
4006
- REF_TRANSACTION_CLOSED = 1
4007
-};
4008
-
4009
-/*
4010
- * Data structure for holding a reference transaction, which can
4011
- * consist of checks and updates to multiple references, carried out
4012
- * as atomically as possible. This structure is opaque to callers.
4013
- */
4014
-struct ref_transaction {
4015
- struct ref_update **updates;
4016
- size_t alloc;
4017
- size_t nr;
4018
- enum ref_transaction_state state;
4019
-};
4020
-
3865
struct ref_transaction *ref_transaction_begin(struct strbuf *err)
3866
{
3867
assert(err);
refs/refs-internal.h
new
+180
@@ -0,0 +1,180 @@
1
+#ifndef REFS_REFS_INTERNAL_H
2
+#define REFS_REFS_INTERNAL_H
3
+
4
+/*
5
+ * Data structures and functions for the internal use of the refs
6
+ * module. Code outside of the refs module should use only the public
7
+ * functions defined in "refs.h", and should *not* include this file.
8
+ */
9
+
10
+/*
11
+ * Flag passed to lock_ref_sha1_basic() telling it to tolerate broken
12
+ * refs (i.e., because the reference is about to be deleted anyway).
13
+ */
14
+#define REF_DELETING 0x02
15
+
16
+/*
17
+ * Used as a flag in ref_update::flags when a loose ref is being
18
+ * pruned.
19
+ */
20
+#define REF_ISPRUNING 0x04
21
+
22
+/*
23
+ * Used as a flag in ref_update::flags when the reference should be
24
+ * updated to new_sha1.
25
+ */
26
+#define REF_HAVE_NEW 0x08
27
+
28
+/*
29
+ * Used as a flag in ref_update::flags when old_sha1 should be
30
+ * checked.
31
+ */
32
+#define REF_HAVE_OLD 0x10
33
+
34
+/*
35
+ * Used as a flag in ref_update::flags when the lockfile needs to be
36
+ * committed.
37
+ */
38
+#define REF_NEEDS_COMMIT 0x20
39
+
40
+/*
41
+ * 0x40 is REF_FORCE_CREATE_REFLOG, so skip it if you're adding a
42
+ * value to ref_update::flags
43
+ */
44
+
45
+/*
46
+ * Return true iff refname is minimally safe. "Safe" here means that
47
+ * deleting a loose reference by this name will not do any damage, for
48
+ * example by causing a file that is not a reference to be deleted.
49
+ * This function does not check that the reference name is legal; for
50
+ * that, use check_refname_format().
51
+ *
52
+ * We consider a refname that starts with "refs/" to be safe as long
53
+ * as any ".." components that it might contain do not escape "refs/".
54
+ * Names that do not start with "refs/" are considered safe iff they
55
+ * consist entirely of upper case characters and '_' (like "HEAD" and
56
+ * "MERGE_HEAD" but not "config" or "FOO/BAR").
57
+ */
58
+int refname_is_safe(const char *refname);
59
+
60
+enum peel_status {
61
+ /* object was peeled successfully: */
62
+ PEEL_PEELED = 0,
63
+
64
+ /*
65
+ * object cannot be peeled because the named object (or an
66
+ * object referred to by a tag in the peel chain), does not
67
+ * exist.
68
+ */
69
+ PEEL_INVALID = -1,
70
+
71
+ /* object cannot be peeled because it is not a tag: */
72
+ PEEL_NON_TAG = -2,
73
+
74
+ /* ref_entry contains no peeled value because it is a symref: */
75
+ PEEL_IS_SYMREF = -3,
76
+
77
+ /*
78
+ * ref_entry cannot be peeled because it is broken (i.e., the
79
+ * symbolic reference cannot even be resolved to an object
80
+ * name):
81
+ */
82
+ PEEL_BROKEN = -4
83
+};
84
+
85
+/*
86
+ * Peel the named object; i.e., if the object is a tag, resolve the
87
+ * tag recursively until a non-tag is found. If successful, store the
88
+ * result to sha1 and return PEEL_PEELED. If the object is not a tag
89
+ * or is not valid, return PEEL_NON_TAG or PEEL_INVALID, respectively,
90
+ * and leave sha1 unchanged.
91
+ */
92
+enum peel_status peel_object(const unsigned char *name, unsigned char *sha1);
93
+
94
+/*
95
+ * Return 0 if a reference named refname could be created without
96
+ * conflicting with the name of an existing reference. Otherwise,
97
+ * return a negative value and write an explanation to err. If extras
98
+ * is non-NULL, it is a list of additional refnames with which refname
99
+ * is not allowed to conflict. If skip is non-NULL, ignore potential
100
+ * conflicts with refs in skip (e.g., because they are scheduled for
101
+ * deletion in the same operation). Behavior is undefined if the same
102
+ * name is listed in both extras and skip.
103
+ *
104
+ * Two reference names conflict if one of them exactly matches the
105
+ * leading components of the other; e.g., "foo/bar" conflicts with
106
+ * both "foo" and with "foo/bar/baz" but not with "foo/bar" or
107
+ * "foo/barbados".
108
+ *
109
+ * extras and skip must be sorted.
110
+ */
111
+int verify_refname_available(const char *newname,
112
+ struct string_list *extras,
113
+ struct string_list *skip,
114
+ struct strbuf *err);
115
+
116
+/*
117
+ * Copy the reflog message msg to buf, which has been allocated sufficiently
118
+ * large, while cleaning up the whitespaces. Especially, convert LF to space,
119
+ * because reflog file is one line per entry.
120
+ */
121
+int copy_reflog_msg(char *buf, const char *msg);
122
+
123
+int should_autocreate_reflog(const char *refname);
124
+
125
+/**
126
+ * Information needed for a single ref update. Set new_sha1 to the new
127
+ * value or to null_sha1 to delete the ref. To check the old value
128
+ * while the ref is locked, set (flags & REF_HAVE_OLD) and set
129
+ * old_sha1 to the old value, or to null_sha1 to ensure the ref does
130
+ * not exist before update.
131
+ */
132
+struct ref_update {
133
+ /*
134
+ * If (flags & REF_HAVE_NEW), set the reference to this value:
135
+ */
136
+ unsigned char new_sha1[20];
137
+ /*
138
+ * If (flags & REF_HAVE_OLD), check that the reference
139
+ * previously had this value:
140
+ */
141
+ unsigned char old_sha1[20];
142
+ /*
143
+ * One or more of REF_HAVE_NEW, REF_HAVE_OLD, REF_NODEREF,
144
+ * REF_DELETING, and REF_ISPRUNING:
145
+ */
146
+ unsigned int flags;
147
+ struct ref_lock *lock;
148
+ int type;
149
+ char *msg;
150
+ const char refname[FLEX_ARRAY];
151
+};
152
+
153
+/*
154
+ * Transaction states.
155
+ * OPEN: The transaction is in a valid state and can accept new updates.
156
+ * An OPEN transaction can be committed.
157
+ * CLOSED: A closed transaction is no longer active and no other operations
158
+ * than free can be used on it in this state.
159
+ * A transaction can either become closed by successfully committing
160
+ * an active transaction or if there is a failure while building
161
+ * the transaction thus rendering it failed/inactive.
162
+ */
163
+enum ref_transaction_state {
164
+ REF_TRANSACTION_OPEN = 0,
165
+ REF_TRANSACTION_CLOSED = 1
166
+};
167
+
168
+/*
169
+ * Data structure for holding a reference transaction, which can
170
+ * consist of checks and updates to multiple references, carried out
171
+ * as atomically as possible. This structure is opaque to callers.
172
+ */
173
+struct ref_transaction {
174
+ struct ref_update **updates;
175
+ size_t alloc;
176
+ size_t nr;
177
+ enum ref_transaction_state state;
178
+};
179
+
180
+#endif /* REFS_REFS_INTERNAL_H */