Coverage Report

Created: 2026-10-17 07:15

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
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
146
int ends_with_path_components(const char *path, const char *components);
147
148
int calc_shared_perm(struct repository *repo, int mode);
149
int adjust_shared_perm(struct repository *repo, const char *path);
150
151
char *interpolate_path(const char *path, int real_home);
152
153
const char *remove_leading_path(const char *in, const char *prefix);
154
const char *relative_path(const char *in, const char *prefix, struct strbuf *sb);
155
int normalize_path_copy_len(char *dst, const char *src, int *prefix_len);
156
int normalize_path_copy(char *dst, const char *src);
157
/**
158
 * Normalize in-place the path contained in the strbuf. If an error occurs,
159
 * the contents of "sb" are left untouched, and -1 is returned.
160
 */
161
int strbuf_normalize_path(struct strbuf *src);
162
int longest_ancestor_length(const char *path, struct string_list *prefixes);
163
char *strip_path_suffix(const char *path, const char *suffix);
164
int daemon_avoid_alias(const char *path);
165
166
/*
167
 * These functions match their is_hfs_dotgit() counterparts; see utf8.h for
168
 * details.
169
 */
170
int is_ntfs_dotgit(const char *name);
171
int is_ntfs_dotgitmodules(const char *name);
172
int is_ntfs_dotgitignore(const char *name);
173
int is_ntfs_dotgitattributes(const char *name);
174
int is_ntfs_dotmailmap(const char *name);
175
176
/*
177
 * Returns true iff "str" could be confused as a command-line option when
178
 * passed to a sub-program like "ssh". Note that this has nothing to do with
179
 * shell-quoting, which should be handled separately; we're assuming here that
180
 * the string makes it verbatim to the sub-program.
181
 */
182
int looks_like_command_line_option(const char *str);
183
184
/**
185
 * Return a newly allocated string with the evaluation of
186
 * "$XDG_CONFIG_HOME/$subdir/$filename" if $XDG_CONFIG_HOME is non-empty, otherwise
187
 * "$HOME/.config/$subdir/$filename". Return NULL upon error.
188
 */
189
char *xdg_config_home_for(const char *subdir, const char *filename);
190
191
/**
192
 * Return a newly allocated string with the evaluation of
193
 * "$XDG_CONFIG_HOME/git/$filename" if $XDG_CONFIG_HOME is non-empty, otherwise
194
 * "$HOME/.config/git/$filename". Return NULL upon error.
195
 */
196
char *xdg_config_home(const char *filename);
197
198
/**
199
 * Return a newly allocated string with the evaluation of
200
 * "$XDG_CACHE_HOME/git/$filename" if $XDG_CACHE_HOME is non-empty, otherwise
201
 * "$HOME/.cache/git/$filename". Return NULL upon error.
202
 */
203
char *xdg_cache_home(const char *filename);
204
205
/*
206
 * Create a directory and (if share is nonzero) adjust its permissions
207
 * according to the shared_repository setting. Only use this for
208
 * directories under $GIT_DIR.  Don't use it for working tree
209
 * directories.
210
 */
211
void safe_create_dir(struct repository *repo, const char *dir, int share);
212
213
/*
214
 * Similar to `safe_create_dir()`, but with two differences:
215
 *
216
 *   - It knows to resolve gitlink files for symlinked worktrees.
217
 *
218
 *   - It always adjusts shared permissions.
219
 *
220
 * Returns a negative error code on error, 0 on success.
221
 */
222
int safe_create_dir_in_gitdir(struct repository *repo, const char *path);
223
224
/*
225
 * Create the directory containing the named path, using care to be
226
 * somewhat safe against races. Return one of the scld_error values to
227
 * indicate success/failure. On error, set errno to describe the
228
 * problem.
229
 *
230
 * SCLD_VANISHED indicates that one of the ancestor directories of the
231
 * path existed at one point during the function call and then
232
 * suddenly vanished, probably because another process pruned the
233
 * directory while we were working.  To be robust against this kind of
234
 * race, callers might want to try invoking the function again when it
235
 * returns SCLD_VANISHED.
236
 *
237
 * safe_create_leading_directories() temporarily changes path while it
238
 * is working but restores it before returning.
239
 * safe_create_leading_directories_const() doesn't modify path, even
240
 * temporarily. Both these variants adjust the permissions of the
241
 * created directories to honor core.sharedRepository, so they are best
242
 * suited for files inside the git dir. For working tree files, use
243
 * safe_create_leading_directories_no_share() instead, as it ignores
244
 * the core.sharedRepository setting.
245
 */
246
enum scld_error {
247
  SCLD_OK = 0,
248
  SCLD_FAILED = -1,
249
  SCLD_PERMS = -2,
250
  SCLD_EXISTS = -3,
251
  SCLD_VANISHED = -4
252
};
253
enum scld_error safe_create_leading_directories(struct repository *repo, char *path);
254
enum scld_error safe_create_leading_directories_const(struct repository *repo,
255
                  const char *path);
256
enum scld_error safe_create_leading_directories_no_share(char *path);
257
258
/*
259
 * Create a file, potentially creating its leading directories in case they
260
 * don't exist. Returns the return value of the open(3p) call.
261
 */
262
int safe_create_file_with_leading_directories(struct repository *repo,
263
                const char *path);
264
265
/**
266
 * The formatting strategy to apply when writing a path into a buffer.
267
 */
268
enum path_format {
269
  /* Output the path exactly as-is without any modifications. */
270
  PATH_FORMAT_UNMODIFIED,
271
272
  /* Output a path relative to the provided directory prefix. */
273
  PATH_FORMAT_RELATIVE,
274
275
  /* Output a relative path only if the path shares a root with the prefix. */
276
  PATH_FORMAT_RELATIVE_IF_SHARED,
277
278
  /* Output a fully resolved, absolute canonical path. */
279
  PATH_FORMAT_CANONICAL
280
};
281
282
/**
283
 * Format a path according to the specified formatting strategy and store
284
 * the result in the given strbuf, replacing any existing contents.
285
 *
286
 * `dest`   : The string buffer to store the formatted path into.
287
 * `path`   : The path string that needs to be formatted.
288
 * `prefix` : The directory prefix to calculate relative offsets against.
289
 * Pass NULL to default to the current working directory where applicable.
290
 * `format` : The formatting behavior rule to execute.
291
 */
292
void format_path(struct strbuf *dest, const char *path,
293
     const char *prefix, enum path_format format);
294
295
# ifdef USE_THE_REPOSITORY_VARIABLE
296
#  include "strbuf.h"
297
#  include "repository.h"
298
299
#define GIT_PATH_FUNC(func, filename) \
300
  const char *func(void) \
301
0
  { \
302
0
    static char *ret; \
303
0
    if (!ret) \
304
0
      ret = repo_git_path(the_repository, filename); \
305
0
    return ret; \
306
0
  }
Unexecuted instantiation: dir.c:git_path_info_exclude
Unexecuted instantiation: fsm-ipc-unix.c:fsmonitor_ipc__get_default_path
Unexecuted instantiation: attr.c:git_path_info_attributes
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: 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: rerere.c:git_path_rr_cache
307
308
# endif /* USE_THE_REPOSITORY_VARIABLE */
309
310
#endif /* PATH_H */