]>
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 | * |
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 Object to which this branch should point. This object | |
42 | * must belong to the given `repo` and can either be a git_commit or a | |
43 | * git_tag. When a git_tag is being passed, it should be dereferencable | |
44 | * to a git_commit which oid will be used as the target of the branch. | |
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( | |
cfbe4be3 | 53 | git_reference **out, |
f0244463 | 54 | git_repository *repo, |
731df570 | 55 | const char *branch_name, |
cfbe4be3 | 56 | const git_commit *target, |
731df570 | 57 | int force); |
58 | ||
59 | /** | |
60 | * Delete an existing branch reference. | |
61 | * | |
62eafd06 VM |
62 | * If the branch is successfully deleted, the passed reference |
63 | * object will be freed and invalidated. | |
731df570 | 64 | * |
62eafd06 | 65 | * @param branch A valid reference representing a branch |
1c947daa | 66 | * @return 0 on success, or an error code. |
731df570 | 67 | */ |
1c947daa | 68 | GIT_EXTERN(int) git_branch_delete(git_reference *branch); |
731df570 | 69 | |
a8fd805e | 70 | /** |
71 | * Loop over all the branches and issue a callback for each one. | |
72 | * | |
5dca2010 RB |
73 | * If the callback returns a non-zero value, this will stop looping. |
74 | * | |
a8fd805e | 75 | * @param repo Repository where to find the branches. |
76 | * | |
77 | * @param list_flags Filtering flags for the branch | |
78 | * listing. Valid values are GIT_BRANCH_LOCAL, GIT_BRANCH_REMOTE | |
79 | * or a combination of the two. | |
80 | * | |
81 | * @param branch_cb Callback to invoke per found branch. | |
82 | * | |
83 | * @param payload Extra parameter to callback function. | |
84 | * | |
5dca2010 | 85 | * @return 0 on success, GIT_EUSER on non-zero callback, or error code |
a8fd805e | 86 | */ |
87 | GIT_EXTERN(int) git_branch_foreach( | |
88 | git_repository *repo, | |
89 | unsigned int list_flags, | |
90 | int (*branch_cb)( | |
91 | const char *branch_name, | |
92 | git_branch_t branch_type, | |
93 | void *payload), | |
94 | void *payload | |
95 | ); | |
96 | ||
4615f0f7 | 97 | /** |
bf9e8cc8 | 98 | * Move/rename an existing local branch reference. |
4615f0f7 | 99 | * |
62173038 | 100 | * The new branch name will be checked for validity. |
101 | * See `git_tag_create()` for rules about valid names. | |
102 | * | |
bf9e8cc8 | 103 | * @param branch Current underlying reference of the branch. |
4615f0f7 | 104 | * |
105 | * @param new_branch_name Target name of the branch once the move | |
106 | * is performed; this name is validated for consistency. | |
107 | * | |
108 | * @param force Overwrite existing branch. | |
109 | * | |
62173038 | 110 | * @return 0 on success, GIT_EINVALIDSPEC or an error code. |
4615f0f7 | 111 | */ |
112 | GIT_EXTERN(int) git_branch_move( | |
bf9e8cc8 | 113 | git_reference *branch, |
4615f0f7 | 114 | const char *new_branch_name, |
115 | int force); | |
116 | ||
eed378b6 | 117 | /** |
118 | * Lookup a branch by its name in a repository. | |
119 | * | |
120 | * The generated reference must be freed by the user. | |
121 | * | |
62173038 | 122 | * The branch name will be checked for validity. |
123 | * See `git_tag_create()` for rules about valid names. | |
124 | * | |
cfbe4be3 | 125 | * @param out pointer to the looked-up branch reference |
eed378b6 | 126 | * |
127 | * @param repo the repository to look up the branch | |
128 | * | |
129 | * @param branch_name Name of the branch to be looked-up; | |
130 | * this name is validated for consistency. | |
131 | * | |
132 | * @param branch_type Type of the considered branch. This should | |
133 | * be valued with either GIT_BRANCH_LOCAL or GIT_BRANCH_REMOTE. | |
134 | * | |
135 | * @return 0 on success; GIT_ENOTFOUND when no matching branch | |
62173038 | 136 | * exists, GIT_EINVALIDSPEC, otherwise an error code. |
eed378b6 | 137 | */ |
138 | GIT_EXTERN(int) git_branch_lookup( | |
cfbe4be3 | 139 | git_reference **out, |
eed378b6 | 140 | git_repository *repo, |
141 | const char *branch_name, | |
142 | git_branch_t branch_type); | |
143 | ||
fb910281 | 144 | /** |
145 | * Return the reference supporting the remote tracking branch, | |
146 | * given a local branch reference. | |
147 | * | |
cfbe4be3 | 148 | * @param out Pointer where to store the retrieved |
fb910281 | 149 | * reference. |
150 | * | |
151 | * @param branch Current underlying reference of the branch. | |
152 | * | |
153 | * @return 0 on success; GIT_ENOTFOUND when no remote tracking | |
154 | * reference exists, otherwise an error code. | |
155 | */ | |
156 | GIT_EXTERN(int) git_branch_tracking( | |
cfbe4be3 | 157 | git_reference **out, |
fb910281 | 158 | git_reference *branch); |
159 | ||
0c78f685 | 160 | /** |
161 | * Determine if the current local branch is pointed at by HEAD. | |
162 | * | |
163 | * @param branch Current underlying reference of the branch. | |
164 | * | |
165 | * @return 1 if HEAD points at the branch, 0 if it isn't, | |
166 | * error code otherwise. | |
167 | */ | |
168 | GIT_EXTERN(int) git_branch_is_head( | |
169 | git_reference *branch); | |
170 | ||
731df570 | 171 | /** @} */ |
172 | GIT_END_DECL | |
9c82357b | 173 | #endif |