/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. When no worktree is given, then the path is
 * computed relative to main worktree of the given repository.
 */
const char *worktree_git_path(struct repository *r,
            const struct worktree *wt,
            const char *fmt, ...)
  __attribute__((format (printf, 3, 4)));

/*
 * 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: 2025-12-31 07:02

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