path.h

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