1 /* 2 * Copyright (C) the libgit2 contributors. All rights reserved. 3 * 4 * This file is part of libgit2, distributed under the GNU GPL v2 with 5 * a Linking Exception. For full terms see the included COPYING file. 6 */ 7 #ifndef INCLUDE_git_branch_h__ 8 #define INCLUDE_git_branch_h__ 9 10 #include "common.h" 11 #include "oid.h" 12 #include "types.h" 13 14 /** 15 * @file git2/branch.h 16 * @brief Git branch parsing routines 17 * @defgroup git_branch Git branch management 18 * @ingroup Git 19 * @{ 20 */ 21 GIT_BEGIN_DECL 22 23 /** 24 * Create a new branch pointing at a target commit 25 * 26 * A new direct reference will be created pointing to 27 * this target commit. If `force` is true and a reference 28 * already exists with the given name, it'll be replaced. 29 * 30 * The returned reference must be freed by the user. 31 * 32 * The branch name will be checked for validity. 33 * See `git_tag_create()` for rules about valid names. 34 * 35 * @param out Pointer where to store the underlying reference. 36 * 37 * @param branch_name Name for the branch; this name is 38 * validated for consistency. It should also not conflict with 39 * an already existing branch name. 40 * 41 * @param target Commit to which this branch should point. This object 42 * must belong to the given `repo`. 43 * 44 * @param force Overwrite existing branch. 45 * 46 * @return 0, GIT_EINVALIDSPEC or an error code. 47 * A proper reference is written in the refs/heads namespace 48 * pointing to the provided target commit. 49 */ 50 GIT_EXTERN(int) git_branch_create( 51 git_reference **out, 52 git_repository *repo, 53 const char *branch_name, 54 const git_commit *target, 55 int force); 56 57 /** 58 * Create a new branch pointing at a target commit 59 * 60 * This behaves like `git_branch_create()` but takes an annotated 61 * commit, which lets you specify which extended sha syntax string was 62 * specified by a user, allowing for more exact reflog messages. 63 * 64 * See the documentation for `git_branch_create()`. 65 * 66 * @see git_branch_create 67 */ 68 GIT_EXTERN(int) git_branch_create_from_annotated( 69 git_reference **ref_out, 70 git_repository *repository, 71 const char *branch_name, 72 const git_annotated_commit *commit, 73 int force); 74 75 /** 76 * Delete an existing branch reference. 77 * 78 * Note that if the deletion succeeds, the reference object will not 79 * be valid anymore, and should be freed immediately by the user using 80 * `git_reference_free()`. 81 * 82 * @param branch A valid reference representing a branch 83 * @return 0 on success, or an error code. 84 */ 85 GIT_EXTERN(int) git_branch_delete(git_reference *branch); 86 87 /** Iterator type for branches */ 88 typedef struct git_branch_iterator git_branch_iterator; 89 90 /** 91 * Create an iterator which loops over the requested branches. 92 * 93 * @param out the iterator 94 * @param repo Repository where to find the branches. 95 * @param list_flags Filtering flags for the branch 96 * listing. Valid values are GIT_BRANCH_LOCAL, GIT_BRANCH_REMOTE 97 * or GIT_BRANCH_ALL. 98 * 99 * @return 0 on success or an error code 100 */ 101 GIT_EXTERN(int) git_branch_iterator_new( 102 git_branch_iterator **out, 103 git_repository *repo, 104 git_branch_t list_flags); 105 106 /** 107 * Retrieve the next branch from the iterator 108 * 109 * @param out the reference 110 * @param out_type the type of branch (local or remote-tracking) 111 * @param iter the branch iterator 112 * @return 0 on success, GIT_ITEROVER if there are no more branches or an error code. 113 */ 114 GIT_EXTERN(int) git_branch_next(git_reference **out, git_branch_t *out_type, git_branch_iterator *iter); 115 116 /** 117 * Free a branch iterator 118 * 119 * @param iter the iterator to free 120 */ 121 GIT_EXTERN(void) git_branch_iterator_free(git_branch_iterator *iter); 122 123 /** 124 * Move/rename an existing local branch reference. 125 * 126 * The new branch name will be checked for validity. 127 * See `git_tag_create()` for rules about valid names. 128 * 129 * Note that if the move succeeds, the old reference object will not 130 + be valid anymore, and should be freed immediately by the user using 131 + `git_reference_free()`. 132 * 133 * @param out New reference object for the updated name. 134 * 135 * @param branch Current underlying reference of the branch. 136 * 137 * @param new_branch_name Target name of the branch once the move 138 * is performed; this name is validated for consistency. 139 * 140 * @param force Overwrite existing branch. 141 * 142 * @return 0 on success, GIT_EINVALIDSPEC or an error code. 143 */ 144 GIT_EXTERN(int) git_branch_move( 145 git_reference **out, 146 git_reference *branch, 147 const char *new_branch_name, 148 int force); 149 150 /** 151 * Lookup a branch by its name in a repository. 152 * 153 * The generated reference must be freed by the user. 154 * The branch name will be checked for validity. 155 * 156 * @see git_tag_create for rules about valid names. 157 * 158 * @param out pointer to the looked-up branch reference 159 * @param repo the repository to look up the branch 160 * @param branch_name Name of the branch to be looked-up; 161 * this name is validated for consistency. 162 * @param branch_type Type of the considered branch. This should 163 * be valued with either GIT_BRANCH_LOCAL or GIT_BRANCH_REMOTE. 164 * 165 * @return 0 on success; GIT_ENOTFOUND when no matching branch 166 * exists, GIT_EINVALIDSPEC, otherwise an error code. 167 */ 168 GIT_EXTERN(int) git_branch_lookup( 169 git_reference **out, 170 git_repository *repo, 171 const char *branch_name, 172 git_branch_t branch_type); 173 174 /** 175 * Get the branch name 176 * 177 * Given a reference object, this will check that it really is a branch (ie. 178 * it lives under "refs/heads/" or "refs/remotes/"), and return the branch part 179 * of it. 180 * 181 * @param out Pointer to the abbreviated reference name. 182 * Owned by ref, do not free. 183 * 184 * @param ref A reference object, ideally pointing to a branch 185 * 186 * @return 0 on success; GIT_EINVALID if the reference isn't either a local or 187 * remote branch, otherwise an error code. 188 */ 189 GIT_EXTERN(int) git_branch_name( 190 const char **out, 191 const git_reference *ref); 192 193 /** 194 * Get the upstream of a branch 195 * 196 * Given a reference, this will return a new reference object corresponding 197 * to its remote tracking branch. The reference must be a local branch. 198 * 199 * @see git_branch_upstream_name for details on the resolution. 200 * 201 * @param out Pointer where to store the retrieved reference. 202 * @param branch Current underlying reference of the branch. 203 * 204 * @return 0 on success; GIT_ENOTFOUND when no remote tracking 205 * reference exists, otherwise an error code. 206 */ 207 GIT_EXTERN(int) git_branch_upstream( 208 git_reference **out, 209 const git_reference *branch); 210 211 /** 212 * Set a branch's upstream branch 213 * 214 * This will update the configuration to set the branch named `branch_name` as the upstream of `branch`. 215 * Pass a NULL name to unset the upstream information. 216 * 217 * @note the actual tracking reference must have been already created for the 218 * operation to succeed. 219 * 220 * @param branch the branch to configure 221 * @param branch_name remote-tracking or local branch to set as upstream. 222 * 223 * @return 0 on success; GIT_ENOTFOUND if there's no branch named `branch_name` 224 * or an error code 225 */ 226 GIT_EXTERN(int) git_branch_set_upstream( 227 git_reference *branch, 228 const char *branch_name); 229 230 /** 231 * Get the upstream name of a branch 232 * 233 * Given a local branch, this will return its remote-tracking branch information, 234 * as a full reference name, ie. "feature/nice" would become 235 * "refs/remote/origin/feature/nice", depending on that branch's configuration. 236 * 237 * @param out the buffer into which the name will be written. 238 * @param repo the repository where the branches live. 239 * @param refname reference name of the local branch. 240 * 241 * @return 0 on success, GIT_ENOTFOUND when no remote tracking reference exists, 242 * or an error code. 243 */ 244 GIT_EXTERN(int) git_branch_upstream_name( 245 git_buf *out, 246 git_repository *repo, 247 const char *refname); 248 249 /** 250 * Determine if HEAD points to the given branch 251 * 252 * @param branch A reference to a local branch. 253 * 254 * @return 1 if HEAD points at the branch, 0 if it isn't, or a negative value 255 * as an error code. 256 */ 257 GIT_EXTERN(int) git_branch_is_head( 258 const git_reference *branch); 259 260 /** 261 * Determine if any HEAD points to the current branch 262 * 263 * This will iterate over all known linked repositories (usually in the form of 264 * worktrees) and report whether any HEAD is pointing at the current branch. 265 * 266 * @param branch A reference to a local branch. 267 * 268 * @return 1 if branch is checked out, 0 if it isn't, an error code otherwise. 269 */ 270 GIT_EXTERN(int) git_branch_is_checked_out( 271 const git_reference *branch); 272 273 /** 274 * Find the remote name of a remote-tracking branch 275 * 276 * This will return the name of the remote whose fetch refspec is matching 277 * the given branch. E.g. given a branch "refs/remotes/test/master", it will 278 * extract the "test" part. If refspecs from multiple remotes match, 279 * the function will return GIT_EAMBIGUOUS. 280 * 281 * @param out The buffer into which the name will be written. 282 * @param repo The repository where the branch lives. 283 * @param refname complete name of the remote tracking branch. 284 * 285 * @return 0 on success, GIT_ENOTFOUND when no matching remote was found, 286 * GIT_EAMBIGUOUS when the branch maps to several remotes, 287 * otherwise an error code. 288 */ 289 GIT_EXTERN(int) git_branch_remote_name( 290 git_buf *out, 291 git_repository *repo, 292 const char *refname); 293 294 /** 295 * Retrieve the upstream remote of a local branch 296 * 297 * This will return the currently configured "branch.*.remote" for a given 298 * branch. This branch must be local. 299 * 300 * @param buf the buffer into which to write the name 301 * @param repo the repository in which to look 302 * @param refname the full name of the branch 303 * @return 0 or an error code 304 */ 305 GIT_EXTERN(int) git_branch_upstream_remote(git_buf *buf, git_repository *repo, const char *refname); 306 307 /** 308 * Determine whether a branch name is valid, meaning that (when prefixed 309 * with `refs/heads/`) that it is a valid reference name, and that any 310 * additional branch name restrictions are imposed (eg, it cannot start 311 * with a `-`). 312 * 313 * @param valid output pointer to set with validity of given branch name 314 * @param name a branch name to test 315 * @return 0 on success or an error code 316 */ 317 GIT_EXTERN(int) git_branch_name_is_valid(int *valid, const char *name); 318 319 /** @} */ 320 GIT_END_DECL 321 #endif 322