/src/git/path.h

Source
#ifndef PATH_H
#define PATH_H

struct repository;
struct strbuf;
struct string_list;
struct worktree;

/*
 * The result to all functions which return statically allocated memory may be
 * overwritten by another call to _any_ one of these functions. Consider using
 * the safer variants which operate on strbufs or return allocated memory.
 */

/*
 * Return a statically allocated path.
 */
const char *mkpath(const char *fmt, ...)
  __attribute__((format (printf, 1, 2)));

/*
 * Return a path.
 */
char *mkpathdup(const char *fmt, ...)
  __attribute__((format (printf, 1, 2)));

/*
 * The `repo_common_path` family of functions will construct a path into a
 * repository's common git directory, which is shared by all worktrees.
 */
char *repo_common_path(const struct repository *repo,
           const char *fmt, ...)
  __attribute__((format (printf, 2, 3)));
const char *repo_common_path_append(const struct repository *repo,
            struct strbuf *sb,
            const char *fmt, ...)
  __attribute__((format (printf, 3, 4)));
const char *repo_common_path_replace(const struct repository *repo,
             struct strbuf *sb,
             const char *fmt, ...)
  __attribute__((format (printf, 3, 4)));

/*
 * The `repo_git_path` family of functions will construct a path into a repository's
 * git directory.
 *
 * These functions will perform adjustments to the resultant path to account
 * for special paths which are either considered common among worktrees (e.g.
 * paths into the object directory) or have been explicitly set via an
 * environment variable or config (e.g. path to the index file).
 *
 * For an exhaustive list of the adjustments made look at `common_list` and
 * `adjust_git_path` in path.c.
 */
char *repo_git_path(struct repository *repo,
        const char *fmt, ...)
  __attribute__((format (printf, 2, 3)));
const char *repo_git_path_append(struct repository *repo,
         struct strbuf *sb,
         const char *fmt, ...)
  __attribute__((format (printf, 3, 4)));
const char *repo_git_path_replace(struct repository *repo,
          struct strbuf *sb,
          const char *fmt, ...)
  __attribute__((format (printf, 3, 4)));

/*
 * Similar to repo_git_path() but can produce paths for a specified
 * worktree instead of current one.
 */
const char *worktree_git_path(const struct worktree *wt,
            const char *fmt, ...)
  __attribute__((format (printf, 2, 3)));

/*
 * The `repo_worktree_path` family of functions will construct a path into a
 * repository's worktree.
 *
 * Returns a `NULL` pointer in case the repository has no worktree.
 */
char *repo_worktree_path(const struct repository *repo,
        const char *fmt, ...)
  __attribute__((format (printf, 2, 3)));
const char *repo_worktree_path_append(const struct repository *repo,
              struct strbuf *sb,
              const char *fmt, ...)
  __attribute__((format (printf, 3, 4)));
const char *repo_worktree_path_replace(const struct repository *repo,
               struct strbuf *sb,
               const char *fmt, ...)
  __attribute__((format (printf, 3, 4)));

/*
 * The `repo_submodule_path` family of functions will construct a path into a
 * submodule's git directory located at `path`. `path` must be a submodule path
 * as found in the index and must be part of the given repository.
 *
 * Returns a `NULL` pointer in case the submodule cannot be found.
 */
char *repo_submodule_path(struct repository *repo,
        const char *path,
        const char *fmt, ...)
  __attribute__((format (printf, 3, 4)));
const char *repo_submodule_path_append(struct repository *repo,
               struct strbuf *sb,
               const char *path,
               const char *fmt, ...)
  __attribute__((format (printf, 4, 5)));
const char *repo_submodule_path_replace(struct repository *repo,
          struct strbuf *sb,
          const char *path,
          const char *fmt, ...)
  __attribute__((format (printf, 4, 5)));

void report_linked_checkout_garbage(struct repository *r);

/*
 * You can define a static memoized git path like:
 *
 *    static REPO_GIT_PATH_FUNC(git_path_foo, "FOO")
 *
 * or use one of the global ones below.
 */
#define REPO_GIT_PATH_FUNC(var, filename) \
  const char *git_path_##var(struct repository *r) \
  { \
    if (!r->cached_paths.var) \
      r->cached_paths.var = repo_git_path(r, filename); \
    return r->cached_paths.var; \
  }

const char *git_path_squash_msg(struct repository *r);
const char *git_path_merge_msg(struct repository *r);
const char *git_path_merge_rr(struct repository *r);
const char *git_path_merge_mode(struct repository *r);
const char *git_path_merge_head(struct repository *r);
const char *git_path_fetch_head(struct repository *r);
const char *git_path_shallow(struct repository *r);

int ends_with_path_components(const char *path, const char *components);

int calc_shared_perm(struct repository *repo, int mode);
int adjust_shared_perm(struct repository *repo, const char *path);

char *interpolate_path(const char *path, int real_home);

const char *remove_leading_path(const char *in, const char *prefix);
const char *relative_path(const char *in, const char *prefix, struct strbuf *sb);
int normalize_path_copy_len(char *dst, const char *src, int *prefix_len);
int normalize_path_copy(char *dst, const char *src);
/**
 * Normalize in-place the path contained in the strbuf. If an error occurs,
 * the contents of "sb" are left untouched, and -1 is returned.
 */
int strbuf_normalize_path(struct strbuf *src);
int longest_ancestor_length(const char *path, struct string_list *prefixes);
char *strip_path_suffix(const char *path, const char *suffix);
int daemon_avoid_alias(const char *path);

/*
 * These functions match their is_hfs_dotgit() counterparts; see utf8.h for
 * details.
 */
int is_ntfs_dotgit(const char *name);
int is_ntfs_dotgitmodules(const char *name);
int is_ntfs_dotgitignore(const char *name);
int is_ntfs_dotgitattributes(const char *name);
int is_ntfs_dotmailmap(const char *name);

/*
 * Returns true iff "str" could be confused as a command-line option when
 * passed to a sub-program like "ssh". Note that this has nothing to do with
 * shell-quoting, which should be handled separately; we're assuming here that
 * the string makes it verbatim to the sub-program.
 */
int looks_like_command_line_option(const char *str);

/**
 * Return a newly allocated string with the evaluation of
 * "$XDG_CONFIG_HOME/$subdir/$filename" if $XDG_CONFIG_HOME is non-empty, otherwise
 * "$HOME/.config/$subdir/$filename". Return NULL upon error.
 */
char *xdg_config_home_for(const char *subdir, const char *filename);

/**
 * Return a newly allocated string with the evaluation of
 * "$XDG_CONFIG_HOME/git/$filename" if $XDG_CONFIG_HOME is non-empty, otherwise
 * "$HOME/.config/git/$filename". Return NULL upon error.
 */
char *xdg_config_home(const char *filename);

/**
 * Return a newly allocated string with the evaluation of
 * "$XDG_CACHE_HOME/git/$filename" if $XDG_CACHE_HOME is non-empty, otherwise
 * "$HOME/.cache/git/$filename". Return NULL upon error.
 */
char *xdg_cache_home(const char *filename);

/*
 * Create a directory and (if share is nonzero) adjust its permissions
 * according to the shared_repository setting. Only use this for
 * directories under $GIT_DIR.  Don't use it for working tree
 * directories.
 */
void safe_create_dir(struct repository *repo, const char *dir, int share);

/*
 * Similar to `safe_create_dir()`, but with two differences:
 *
 *   - It knows to resolve gitlink files for symlinked worktrees.
 *
 *   - It always adjusts shared permissions.
 *
 * Returns a negative erorr code on error, 0 on success.
 */
int safe_create_dir_in_gitdir(struct repository *repo, const char *path);

/*
 * Create the directory containing the named path, using care to be
 * somewhat safe against races. Return one of the scld_error values to
 * indicate success/failure. On error, set errno to describe the
 * problem.
 *
 * SCLD_VANISHED indicates that one of the ancestor directories of the
 * path existed at one point during the function call and then
 * suddenly vanished, probably because another process pruned the
 * directory while we were working.  To be robust against this kind of
 * race, callers might want to try invoking the function again when it
 * returns SCLD_VANISHED.
 *
 * safe_create_leading_directories() temporarily changes path while it
 * is working but restores it before returning.
 * safe_create_leading_directories_const() doesn't modify path, even
 * temporarily. Both these variants adjust the permissions of the
 * created directories to honor core.sharedRepository, so they are best
 * suited for files inside the git dir. For working tree files, use
 * safe_create_leading_directories_no_share() instead, as it ignores
 * the core.sharedRepository setting.
 */
enum scld_error {
  SCLD_OK = 0,
  SCLD_FAILED = -1,
  SCLD_PERMS = -2,
  SCLD_EXISTS = -3,
  SCLD_VANISHED = -4
};
enum scld_error safe_create_leading_directories(struct repository *repo, char *path);
enum scld_error safe_create_leading_directories_const(struct repository *repo,
                  const char *path);
enum scld_error safe_create_leading_directories_no_share(char *path);

/*
 * Create a file, potentially creating its leading directories in case they
 * don't exist. Returns the return value of the open(3p) call.
 */
int safe_create_file_with_leading_directories(struct repository *repo,
                const char *path);

# ifdef USE_THE_REPOSITORY_VARIABLE
#  include "strbuf.h"
#  include "repository.h"

#define GIT_PATH_FUNC(func, filename) \
  const char *func(void) \
  { \
    static char *ret; \
    if (!ret) \
      ret = repo_git_path(the_repository, filename); \
    return ret; \
  }

# endif /* USE_THE_REPOSITORY_VARIABLE */

#endif /* PATH_H */

Coverage Report

Created: 2026-03-31 06:24

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		void report_linked_checkout_garbage(struct repository *r);
116
117		/*
118		* You can define a static memoized git path like:
119		*
120		* static REPO_GIT_PATH_FUNC(git_path_foo, "FOO")
121		*
122		* or use one of the global ones below.
123		*/
124		#define REPO_GIT_PATH_FUNC(var, filename) \
125		const char git_path_##var(struct repository r) \
126	0	{ \
127	0	if (!r->cached_paths.var) \
128	0	r->cached_paths.var = repo_git_path(r, filename); \
129	0	return r->cached_paths.var; \
130	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
131
132		const char git_path_squash_msg(struct repository r);
133		const char git_path_merge_msg(struct repository r);
134		const char git_path_merge_rr(struct repository r);
135		const char git_path_merge_mode(struct repository r);
136		const char git_path_merge_head(struct repository r);
137		const char git_path_fetch_head(struct repository r);
138		const char git_path_shallow(struct repository r);
139
140		int ends_with_path_components(const char path, const char components);
141
142		int calc_shared_perm(struct repository *repo, int mode);
143		int adjust_shared_perm(struct repository repo, const char path);
144
145		char interpolate_path(const char path, int real_home);
146
147		const char remove_leading_path(const char in, const char *prefix);
148		const char relative_path(const char in, const char prefix, struct strbuf sb);
149		int normalize_path_copy_len(char dst, const char src, int *prefix_len);
150		int normalize_path_copy(char dst, const char src);
151		/**
152		* Normalize in-place the path contained in the strbuf. If an error occurs,
153		* the contents of "sb" are left untouched, and -1 is returned.
154		*/
155		int strbuf_normalize_path(struct strbuf *src);
156		int longest_ancestor_length(const char path, struct string_list prefixes);
157		char strip_path_suffix(const char path, const char *suffix);
158		int daemon_avoid_alias(const char *path);
159
160		/*
161		* These functions match their is_hfs_dotgit() counterparts; see utf8.h for
162		* details.
163		*/
164		int is_ntfs_dotgit(const char *name);
165		int is_ntfs_dotgitmodules(const char *name);
166		int is_ntfs_dotgitignore(const char *name);
167		int is_ntfs_dotgitattributes(const char *name);
168		int is_ntfs_dotmailmap(const char *name);
169
170		/*
171		* Returns true iff "str" could be confused as a command-line option when
172		* passed to a sub-program like "ssh". Note that this has nothing to do with
173		* shell-quoting, which should be handled separately; we're assuming here that
174		* the string makes it verbatim to the sub-program.
175		*/
176		int looks_like_command_line_option(const char *str);
177
178		/**
179		* Return a newly allocated string with the evaluation of
180		* "$XDG_CONFIG_HOME/$subdir/$filename" if $XDG_CONFIG_HOME is non-empty, otherwise
181		* "$HOME/.config/$subdir/$filename". Return NULL upon error.
182		*/
183		char xdg_config_home_for(const char subdir, const char *filename);
184
185		/**
186		* Return a newly allocated string with the evaluation of
187		* "$XDG_CONFIG_HOME/git/$filename" if $XDG_CONFIG_HOME is non-empty, otherwise
188		* "$HOME/.config/git/$filename". Return NULL upon error.
189		*/
190		char xdg_config_home(const char filename);
191
192		/**
193		* Return a newly allocated string with the evaluation of
194		* "$XDG_CACHE_HOME/git/$filename" if $XDG_CACHE_HOME is non-empty, otherwise
195		* "$HOME/.cache/git/$filename". Return NULL upon error.
196		*/
197		char xdg_cache_home(const char filename);
198
199		/*
200		* Create a directory and (if share is nonzero) adjust its permissions
201		* according to the shared_repository setting. Only use this for
202		* directories under $GIT_DIR. Don't use it for working tree
203		* directories.
204		*/
205		void safe_create_dir(struct repository repo, const char dir, int share);
206
207		/*
208		* Similar to `safe_create_dir()`, but with two differences:
209		*
210		* - It knows to resolve gitlink files for symlinked worktrees.
211		*
212		* - It always adjusts shared permissions.
213		*
214		* Returns a negative erorr code on error, 0 on success.
215		*/
216		int safe_create_dir_in_gitdir(struct repository repo, const char path);
217
218		/*
219		* Create the directory containing the named path, using care to be
220		* somewhat safe against races. Return one of the scld_error values to
221		* indicate success/failure. On error, set errno to describe the
222		* problem.
223		*
224		* SCLD_VANISHED indicates that one of the ancestor directories of the
225		* path existed at one point during the function call and then
226		* suddenly vanished, probably because another process pruned the
227		* directory while we were working. To be robust against this kind of
228		* race, callers might want to try invoking the function again when it
229		* returns SCLD_VANISHED.
230		*
231		* safe_create_leading_directories() temporarily changes path while it
232		* is working but restores it before returning.
233		* safe_create_leading_directories_const() doesn't modify path, even
234		* temporarily. Both these variants adjust the permissions of the
235		* created directories to honor core.sharedRepository, so they are best
236		* suited for files inside the git dir. For working tree files, use
237		* safe_create_leading_directories_no_share() instead, as it ignores
238		* the core.sharedRepository setting.
239		*/
240		enum scld_error {
241		SCLD_OK = 0,
242		SCLD_FAILED = -1,
243		SCLD_PERMS = -2,
244		SCLD_EXISTS = -3,
245		SCLD_VANISHED = -4
246		};
247		enum scld_error safe_create_leading_directories(struct repository repo, char path);
248		enum scld_error safe_create_leading_directories_const(struct repository *repo,
249		const char *path);
250		enum scld_error safe_create_leading_directories_no_share(char *path);
251
252		/*
253		* Create a file, potentially creating its leading directories in case they
254		* don't exist. Returns the return value of the open(3p) call.
255		*/
256		int safe_create_file_with_leading_directories(struct repository *repo,
257		const char *path);
258
259		# ifdef USE_THE_REPOSITORY_VARIABLE
260		# include "strbuf.h"
261		# include "repository.h"
262
263		#define GIT_PATH_FUNC(func, filename) \
264		const char *func(void) \
265	0	{ \
266	0	static char *ret; \
267	0	if (!ret) \
268	0	ret = repo_git_path(the_repository, filename); \
269	0	return ret; \
270	0	} Unexecuted instantiation: attr.c:git_path_info_attributes Unexecuted instantiation: dir.c:git_path_info_exclude 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_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
271
272		# endif /* USE_THE_REPOSITORY_VARIABLE */
273
274		#endif /* PATH_H */