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