Coverage Report

Created: 2026-11-12 06:03

next uncovered line (L), next uncovered region (R), next uncovered branch (B)
/src/git/path.h
Line
Count
Source
1
#ifndef PATH_H
2
#define PATH_H
3
4
struct repository;
5
struct strbuf;
6
struct string_list;
7
struct worktree;
8
9
/*
10
 * The result to all functions which return statically allocated memory may be
11
 * overwritten by another call to _any_ one of these functions. Consider using
12
 * the safer variants which operate on strbufs or return allocated memory.
13
 */
14
15
/*
16
 * Return a statically allocated path.
17
 */
18
const char *mkpath(const char *fmt, ...)
19
  __attribute__((format (printf, 1, 2)));
20
21
/*
22
 * Return a path.
23
 */
24
char *mkpathdup(const char *fmt, ...)
25
  __attribute__((format (printf, 1, 2)));
26
27
/*
28
 * The `repo_common_path` family of functions will construct a path into a
29
 * repository's common git directory, which is shared by all worktrees.
30
 */
31
char *repo_common_path(const struct repository *repo,
32
           const char *fmt, ...)
33
  __attribute__((format (printf, 2, 3)));
34
const char *repo_common_path_append(const struct repository *repo,
35
            struct strbuf *sb,
36
            const char *fmt, ...)
37
  __attribute__((format (printf, 3, 4)));
38
const char *repo_common_path_replace(const struct repository *repo,
39
             struct strbuf *sb,
40
             const char *fmt, ...)
41
  __attribute__((format (printf, 3, 4)));
42
43
/*
44
 * The `repo_git_path` family of functions will construct a path into a repository's
45
 * git directory.
46
 *
47
 * These functions will perform adjustments to the resultant path to account
48
 * for special paths which are either considered common among worktrees (e.g.
49
 * paths into the object directory) or have been explicitly set via an
50
 * environment variable or config (e.g. path to the index file).
51
 *
52
 * For an exhaustive list of the adjustments made look at `common_list` and
53
 * `adjust_git_path` in path.c.
54
 */
55
char *repo_git_path(struct repository *repo,
56
        const char *fmt, ...)
57
  __attribute__((format (printf, 2, 3)));
58
const char *repo_git_path_append(struct repository *repo,
59
         struct strbuf *sb,
60
         const char *fmt, ...)
61
  __attribute__((format (printf, 3, 4)));
62
const char *repo_git_path_replace(struct repository *repo,
63
          struct strbuf *sb,
64
          const char *fmt, ...)
65
  __attribute__((format (printf, 3, 4)));
66
67
/*
68
 * Similar to repo_git_path() but can produce paths for a specified
69
 * worktree instead of current one.
70
 */
71
const char *worktree_git_path(const struct worktree *wt,
72
            const char *fmt, ...)
73
  __attribute__((format (printf, 2, 3)));
74
75
/*
76
 * The `repo_worktree_path` family of functions will construct a path into a
77
 * repository's worktree.
78
 *
79
 * Returns a `NULL` pointer in case the repository has no worktree.
80
 */
81
char *repo_worktree_path(const struct repository *repo,
82
        const char *fmt, ...)
83
  __attribute__((format (printf, 2, 3)));
84
const char *repo_worktree_path_append(const struct repository *repo,
85
              struct strbuf *sb,
86
              const char *fmt, ...)
87
  __attribute__((format (printf, 3, 4)));
88
const char *repo_worktree_path_replace(const struct repository *repo,
89
               struct strbuf *sb,
90
               const char *fmt, ...)
91
  __attribute__((format (printf, 3, 4)));
92
93
/*
94
 * The `repo_submodule_path` family of functions will construct a path into a
95
 * submodule's git directory located at `path`. `path` must be a submodule path
96
 * as found in the index and must be part of the given repository.
97
 *
98
 * Returns a `NULL` pointer in case the submodule cannot be found.
99
 */
100
char *repo_submodule_path(struct repository *repo,
101
        const char *path,
102
        const char *fmt, ...)
103
  __attribute__((format (printf, 3, 4)));
104
const char *repo_submodule_path_append(struct repository *repo,
105
               struct strbuf *sb,
106
               const char *path,
107
               const char *fmt, ...)
108
  __attribute__((format (printf, 4, 5)));
109
const char *repo_submodule_path_replace(struct repository *repo,
110
          struct strbuf *sb,
111
          const char *path,
112
          const char *fmt, ...)
113
  __attribute__((format (printf, 4, 5)));
114
115
/*
116
 * Given a directory name 'dir' (not ending with a trailing '/'),
117
 * determine if 'buf' is equal to 'dir' or has prefix 'dir'+'/'.
118
 */
119
int dir_prefix(const char *buf, const char *dir);
120
121
void report_linked_checkout_garbage(struct repository *r);
122
123
/*
124
 * You can define a static memoized git path like:
125
 *
126
 *    static REPO_GIT_PATH_FUNC(git_path_foo, "FOO")
127
 *
128
 * or use one of the global ones below.
129
 */
130
#define REPO_GIT_PATH_FUNC(var, filename) \
131
  const char *git_path_##var(struct repository *r) \
132
0
  { \
133
0
    if (!r->cached_paths.var) \
134
0
      r->cached_paths.var = repo_git_path(r, filename); \
135
0
    return r->cached_paths.var; \
136
0
  }
Unexecuted instantiation: git_path_squash_msg
Unexecuted instantiation: git_path_merge_msg
Unexecuted instantiation: git_path_merge_rr
Unexecuted instantiation: git_path_merge_mode
Unexecuted instantiation: git_path_merge_head
Unexecuted instantiation: git_path_fetch_head
Unexecuted instantiation: git_path_shallow
Unexecuted instantiation: git_path_merge_labels
137
138
const char *git_path_squash_msg(struct repository *r);
139
const char *git_path_merge_msg(struct repository *r);
140
const char *git_path_merge_rr(struct repository *r);
141
const char *git_path_merge_mode(struct repository *r);
142
const char *git_path_merge_head(struct repository *r);
143
const char *git_path_fetch_head(struct repository *r);
144
const char *git_path_shallow(struct repository *r);
145
const char *git_path_merge_labels(struct repository *r);
146
147
int ends_with_path_components(const char *path, const char *components);
148
149
int calc_shared_perm(struct repository *repo, int mode);
150
int adjust_shared_perm(struct repository *repo, const char *path);
151
152
char *interpolate_path(const char *path, int real_home);
153
154
const char *remove_leading_path(const char *in, const char *prefix);
155
const char *relative_path(const char *in, const char *prefix, struct strbuf *sb);
156
int normalize_path_copy_len(char *dst, const char *src, int *prefix_len);
157
int normalize_path_copy(char *dst, const char *src);
158
/**
159
 * Normalize in-place the path contained in the strbuf. If an error occurs,
160
 * the contents of "sb" are left untouched, and -1 is returned.
161
 */
162
int strbuf_normalize_path(struct strbuf *src);
163
int longest_ancestor_length(const char *path, struct string_list *prefixes);
164
char *strip_path_suffix(const char *path, const char *suffix);
165
int daemon_avoid_alias(const char *path);
166
167
/*
168
 * These functions match their is_hfs_dotgit() counterparts; see utf8.h for
169
 * details.
170
 */
171
int is_ntfs_dotgit(const char *name);
172
int is_ntfs_dotgitmodules(const char *name);
173
int is_ntfs_dotgitignore(const char *name);
174
int is_ntfs_dotgitattributes(const char *name);
175
int is_ntfs_dotmailmap(const char *name);
176
177
/*
178
 * Returns true iff "str" could be confused as a command-line option when
179
 * passed to a sub-program like "ssh". Note that this has nothing to do with
180
 * shell-quoting, which should be handled separately; we're assuming here that
181
 * the string makes it verbatim to the sub-program.
182
 */
183
int looks_like_command_line_option(const char *str);
184
185
/**
186
 * Return a newly allocated string with the evaluation of
187
 * "$XDG_CONFIG_HOME/$subdir/$filename" if $XDG_CONFIG_HOME is non-empty, otherwise
188
 * "$HOME/.config/$subdir/$filename". Return NULL upon error.
189
 */
190
char *xdg_config_home_for(const char *subdir, const char *filename);
191
192
/**
193
 * Return a newly allocated string with the evaluation of
194
 * "$XDG_CONFIG_HOME/git/$filename" if $XDG_CONFIG_HOME is non-empty, otherwise
195
 * "$HOME/.config/git/$filename". Return NULL upon error.
196
 */
197
char *xdg_config_home(const char *filename);
198
199
/**
200
 * Return a newly allocated string with the evaluation of
201
 * "$XDG_CACHE_HOME/git/$filename" if $XDG_CACHE_HOME is non-empty, otherwise
202
 * "$HOME/.cache/git/$filename". Return NULL upon error.
203
 */
204
char *xdg_cache_home(const char *filename);
205
206
/*
207
 * Create a directory and (if share is nonzero) adjust its permissions
208
 * according to the shared_repository setting. Only use this for
209
 * directories under $GIT_DIR.  Don't use it for working tree
210
 * directories.
211
 */
212
void safe_create_dir(struct repository *repo, const char *dir, int share);
213
214
/*
215
 * Similar to `safe_create_dir()`, but with two differences:
216
 *
217
 *   - It knows to resolve gitlink files for symlinked worktrees.
218
 *
219
 *   - It always adjusts shared permissions.
220
 *
221
 * Returns a negative error code on error, 0 on success.
222
 */
223
int safe_create_dir_in_gitdir(struct repository *repo, const char *path);
224
225
/*
226
 * Create the directory containing the named path, using care to be
227
 * somewhat safe against races. Return one of the scld_error values to
228
 * indicate success/failure. On error, set errno to describe the
229
 * problem.
230
 *
231
 * SCLD_VANISHED indicates that one of the ancestor directories of the
232
 * path existed at one point during the function call and then
233
 * suddenly vanished, probably because another process pruned the
234
 * directory while we were working.  To be robust against this kind of
235
 * race, callers might want to try invoking the function again when it
236
 * returns SCLD_VANISHED.
237
 *
238
 * The default variants honor "core.sharedRepository" and temporarily modify
239
 * `path`. Note that this configuration should be honored for all files in the
240
 * git directory. The `no_share()` variants ignore "core.sharedRepository",
241
 * and should be used for working tree files. The `const()` variants do not
242
 * modify `path`.
243
 */
244
enum scld_error {
245
  SCLD_OK = 0,
246
  SCLD_FAILED = -1,
247
  SCLD_PERMS = -2,
248
  SCLD_EXISTS = -3,
249
  SCLD_VANISHED = -4
250
};
251
enum scld_error safe_create_leading_directories(struct repository *repo, char *path);
252
enum scld_error safe_create_leading_directories_const(struct repository *repo,
253
                  const char *path);
254
enum scld_error safe_create_leading_directories_no_share(char *path);
255
enum scld_error safe_create_leading_directories_no_share_const(const char *path);
256
257
/*
258
 * Create a file, potentially creating its leading directories in case they
259
 * don't exist. Returns the return value of the open(3p) call.
260
 */
261
int safe_create_file_with_leading_directories(struct repository *repo,
262
                const char *path);
263
264
/**
265
 * The formatting strategy to apply when writing a path into a buffer.
266
 */
267
enum path_format {
268
  /* Output the path exactly as-is without any modifications. */
269
  PATH_FORMAT_UNMODIFIED,
270
271
  /* Output a path relative to the provided directory prefix. */
272
  PATH_FORMAT_RELATIVE,
273
274
  /* Output a relative path only if the path shares a root with the prefix. */
275
  PATH_FORMAT_RELATIVE_IF_SHARED,
276
277
  /* Output a fully resolved, absolute canonical path. */
278
  PATH_FORMAT_CANONICAL
279
};
280
281
/**
282
 * Format a path according to the specified formatting strategy and store
283
 * the result in the given strbuf, replacing any existing contents.
284
 *
285
 * `dest`   : The string buffer to store the formatted path into.
286
 * `path`   : The path string that needs to be formatted.
287
 * `prefix` : The directory prefix to calculate relative offsets against.
288
 * Pass NULL to default to the current working directory where applicable.
289
 * `format` : The formatting behavior rule to execute.
290
 */
291
void format_path(struct strbuf *dest, const char *path,
292
     const char *prefix, enum path_format format);
293
294
# ifdef USE_THE_REPOSITORY_VARIABLE
295
#  include "strbuf.h"
296
#  include "repository.h"
297
298
#define GIT_PATH_FUNC(func, filename) \
299
  const char *func(void) \
300
0
  { \
301
0
    static char *ret; \
302
0
    if (!ret) \
303
0
      ret = repo_git_path(the_repository, filename); \
304
0
    return ret; \
305
0
  }
Unexecuted instantiation: bisect.c:git_path_bisect_terms
Unexecuted instantiation: bisect.c:git_path_bisect_first_parent
Unexecuted instantiation: bisect.c:git_path_bisect_ancestors_ok
Unexecuted instantiation: bisect.c:git_path_bisect_log
Unexecuted instantiation: bisect.c:git_path_bisect_names
Unexecuted instantiation: bisect.c:git_path_bisect_run
Unexecuted instantiation: bisect.c:git_path_bisect_reset_when_found
Unexecuted instantiation: bisect.c:git_path_bisect_start
Unexecuted instantiation: dir.c:git_path_info_exclude
Unexecuted instantiation: git_path_commit_editmsg
Unexecuted instantiation: rebase_path_todo
Unexecuted instantiation: rebase_path_todo_backup
Unexecuted instantiation: rebase_path_dropped
Unexecuted instantiation: sequencer.c:rebase_path_refs_to_delete
Unexecuted instantiation: sequencer.c:git_path_todo_file
Unexecuted instantiation: sequencer.c:rebase_path_done
Unexecuted instantiation: sequencer.c:rebase_path_head_name
Unexecuted instantiation: sequencer.c:rebase_path_onto
Unexecuted instantiation: sequencer.c:rebase_path_orig_head
Unexecuted instantiation: sequencer.c:rebase_path_quiet
Unexecuted instantiation: sequencer.c:rebase_path_verbose
Unexecuted instantiation: sequencer.c:rebase_path_strategy
Unexecuted instantiation: sequencer.c:rebase_path_strategy_opts
Unexecuted instantiation: sequencer.c:rebase_path_allow_rerere_autoupdate
Unexecuted instantiation: sequencer.c:rebase_path_gpg_sign_opt
Unexecuted instantiation: sequencer.c:rebase_path_signoff
Unexecuted instantiation: sequencer.c:rebase_path_drop_redundant_commits
Unexecuted instantiation: sequencer.c:rebase_path_keep_redundant_commits
Unexecuted instantiation: sequencer.c:rebase_path_cdate_is_adate
Unexecuted instantiation: sequencer.c:rebase_path_ignore_date
Unexecuted instantiation: sequencer.c:rebase_path_reschedule_failed_exec
Unexecuted instantiation: sequencer.c:rebase_path_no_reschedule_failed_exec
Unexecuted instantiation: sequencer.c:rebase_path_trailer
Unexecuted instantiation: sequencer.c:git_path_head_file
Unexecuted instantiation: sequencer.c:git_path_abort_safety_file
Unexecuted instantiation: sequencer.c:git_path_seq_dir
Unexecuted instantiation: sequencer.c:rebase_path_current_fixups
Unexecuted instantiation: sequencer.c:rebase_path_squash_onto
Unexecuted instantiation: sequencer.c:git_path_opts_file
Unexecuted instantiation: sequencer.c:rebase_path_message
Unexecuted instantiation: sequencer.c:rebase_path_amend
Unexecuted instantiation: sequencer.c:rebase_path_fixup_msg
Unexecuted instantiation: sequencer.c:rebase_path_squash_msg
Unexecuted instantiation: sequencer.c:rebase_path_author_script
Unexecuted instantiation: sequencer.c:rebase_path_stopped_sha
Unexecuted instantiation: sequencer.c:rebase_path_rewritten_pending
Unexecuted instantiation: sequencer.c:rebase_path_rewritten_list
Unexecuted instantiation: sequencer.c:rebase_path_patch
Unexecuted instantiation: sequencer.c:rebase_path_msgnum
Unexecuted instantiation: sequencer.c:rebase_path_autostash
Unexecuted instantiation: sequencer.c:rebase_path_msgtotal
Unexecuted instantiation: sequencer.c:rebase_path
Unexecuted instantiation: fsm-ipc-unix.c:fsmonitor_ipc__get_default_path
Unexecuted instantiation: attr.c:git_path_info_attributes
306
307
# endif /* USE_THE_REPOSITORY_VARIABLE */
308
309
#endif /* PATH_H */