path: document path functions
Signed-off-by: Brandon Williams <bmwill@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Brandon Williams committed
Dec 13, 2017 at 10:28 UTC
c07b3adff1ce8d346fe1312a840a7246885442c0
1 file changed
+112
-21
path.h
+112
-21
@@ -4,53 +4,144 @@
4
struct repository;
5
6
/*
7
- * Return a statically allocated filename, either generically (mkpath), in
8
- * the repository directory (git_path), or in a submodule's repository
9
- * directory (git_path_submodule). In all cases, note that the result
10
- * may be overwritten by another call to _any_ of the functions. Consider
11
- * using the safer "dup" or "strbuf" formats below (in some cases, the
12
- * unsafe versions have already been removed).
7
+ * The result to all functions which return statically allocated memory may be
8
+ * overwritten by another call to _any_ one of these functions. Consider using
9
+ * the safer variants which operate on strbufs or return allocated memory.
10
*/
14
-extern const char *mkpath(const char *fmt, ...) __attribute__((format (printf, 1, 2)));
15
-extern const char *git_path(const char *fmt, ...) __attribute__((format (printf, 1, 2)));
16
-extern const char *git_common_path(const char *fmt, ...) __attribute__((format (printf, 1, 2)));
11
12
+/*
13
+ * Return a statically allocated path.
14
+ */
15
+extern const char *mkpath(const char *fmt, ...)
16
+ __attribute__((format (printf, 1, 2)));
17
+
18
+/*
19
+ * Return a path.
20
+ */
21
+extern char *mkpathdup(const char *fmt, ...)
22
+ __attribute__((format (printf, 1, 2)));
23
+
24
+/*
25
+ * Construct a path and place the result in the provided buffer `buf`.
26
+ */
27
extern char *mksnpath(char *buf, size_t n, const char *fmt, ...)
28
__attribute__((format (printf, 3, 4)));
20
-extern void strbuf_git_path(struct strbuf *sb, const char *fmt, ...)
21
- __attribute__((format (printf, 2, 3)));
29
+
30
+/*
31
+ * The `git_common_path` family of functions will construct a path into a
32
+ * repository's common git directory, which is shared by all worktrees.
33
+ */
34
+
35
+/*
36
+ * Constructs a path into the common git directory of repository `repo` and
37
+ * append it in the provided buffer `sb`.
38
+ */
39
extern void strbuf_git_common_path(struct strbuf *sb,
40
const struct repository *repo,
41
const char *fmt, ...)
42
__attribute__((format (printf, 3, 4)));
26
-extern char *git_path_buf(struct strbuf *buf, const char *fmt, ...)
27
- __attribute__((format (printf, 2, 3)));
28
-extern int strbuf_git_path_submodule(struct strbuf *sb, const char *path,
29
- const char *fmt, ...)
30
- __attribute__((format (printf, 3, 4)));
31
-extern char *git_pathdup(const char *fmt, ...)
32
- __attribute__((format (printf, 1, 2)));
33
-extern char *mkpathdup(const char *fmt, ...)
43
+
44
+/*
45
+ * Return a statically allocated path into the main repository's
46
+ * (the_repository) common git directory.
47
+ */
48
+extern const char *git_common_path(const char *fmt, ...)
49
__attribute__((format (printf, 1, 2)));
35
-extern char *git_pathdup_submodule(const char *path, const char *fmt, ...)
36
- __attribute__((format (printf, 2, 3)));
50
51
+
52
+/*
53
+ * The `git_path` family of functions will construct a path into a repository's
54
+ * git directory.
55
+ *
56
+ * These functions will perform adjustments to the resultant path to account
57
+ * for special paths which are either considered common among worktrees (e.g.
58
+ * paths into the object directory) or have been explicitly set via an
59
+ * environment variable or config (e.g. path to the index file).
60
+ *
61
+ * For an exhaustive list of the adjustments made look at `common_list` and
62
+ * `adjust_git_path` in path.c.
63
+ */
64
+
65
+/*
66
+ * Return a path into the git directory of repository `repo`.
67
+ */
68
extern char *repo_git_path(const struct repository *repo,
69
const char *fmt, ...)
70
__attribute__((format (printf, 2, 3)));
71
+
72
+/*
73
+ * Construct a path into the git directory of repository `repo` and append it
74
+ * to the provided buffer `sb`.
75
+ */
76
extern void strbuf_repo_git_path(struct strbuf *sb,
77
const struct repository *repo,
78
const char *fmt, ...)
79
__attribute__((format (printf, 3, 4)));
80
81
+/*
82
+ * Return a statically allocated path into the main repository's
83
+ * (the_repository) git directory.
84
+ */
85
+extern const char *git_path(const char *fmt, ...)
86
+ __attribute__((format (printf, 1, 2)));
87
+
88
+/*
89
+ * Return a path into the main repository's (the_repository) git directory.
90
+ */
91
+extern char *git_pathdup(const char *fmt, ...)
92
+ __attribute__((format (printf, 1, 2)));
93
+
94
+/*
95
+ * Construct a path into the main repository's (the_repository) git directory
96
+ * and place it in the provided buffer `buf`, the contents of the buffer will
97
+ * be overridden.
98
+ */
99
+extern char *git_path_buf(struct strbuf *buf, const char *fmt, ...)
100
+ __attribute__((format (printf, 2, 3)));
101
+
102
+/*
103
+ * Construct a path into the main repository's (the_repository) git directory
104
+ * and append it to the provided buffer `sb`.
105
+ */
106
+extern void strbuf_git_path(struct strbuf *sb, const char *fmt, ...)
107
+ __attribute__((format (printf, 2, 3)));
108
+
109
+/*
110
+ * Return a path into the worktree of repository `repo`.
111
+ *
112
+ * If the repository doesn't have a worktree NULL is returned.
113
+ */
114
extern char *repo_worktree_path(const struct repository *repo,
115
const char *fmt, ...)
116
__attribute__((format (printf, 2, 3)));
117
+
118
+/*
119
+ * Construct a path into the worktree of repository `repo` and append it
120
+ * to the provided buffer `sb`.
121
+ *
122
+ * If the repository doesn't have a worktree nothing will be appended to `sb`.
123
+ */
124
extern void strbuf_repo_worktree_path(struct strbuf *sb,
125
const struct repository *repo,
126
const char *fmt, ...)
127
__attribute__((format (printf, 3, 4)));
128
129
+/*
130
+ * Return a path into a submodule's git directory located at `path`. `path`
131
+ * must only reference a submodule of the main repository (the_repository).
132
+ */
133
+extern char *git_pathdup_submodule(const char *path, const char *fmt, ...)
134
+ __attribute__((format (printf, 2, 3)));
135
+
136
+/*
137
+ * Construct a path into a submodule's git directory located at `path` and
138
+ * append it to the provided buffer `sb`. `path` must only reference a
139
+ * submodule of the main repository (the_repository).
140
+ */
141
+extern int strbuf_git_path_submodule(struct strbuf *sb, const char *path,
142
+ const char *fmt, ...)
143
+ __attribute__((format (printf, 3, 4)));
144
+
145
extern void report_linked_checkout_garbage(void);
146
147
/*