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_rebase_h__ 8 #define INCLUDE_git_rebase_h__ 9 10 #include "common.h" 11 #include "types.h" 12 #include "oid.h" 13 #include "annotated_commit.h" 14 #include "merge.h" 15 #include "checkout.h" 16 #include "commit.h" 17 18 /** 19 * @file git2/rebase.h 20 * @brief Git rebase routines 21 * @defgroup git_rebase Git merge routines 22 * @ingroup Git 23 * @{ 24 */ 25 GIT_BEGIN_DECL 26 27 /** 28 * Rebase options 29 * 30 * Use to tell the rebase machinery how to operate. 31 */ 32 typedef struct { 33 unsigned int version; 34 35 /** 36 * Used by `git_rebase_init`, this will instruct other clients working 37 * on this rebase that you want a quiet rebase experience, which they 38 * may choose to provide in an application-specific manner. This has no 39 * effect upon libgit2 directly, but is provided for interoperability 40 * between Git tools. 41 */ 42 int quiet; 43 44 /** 45 * Used by `git_rebase_init`, this will begin an in-memory rebase, 46 * which will allow callers to step through the rebase operations and 47 * commit the rebased changes, but will not rewind HEAD or update the 48 * repository to be in a rebasing state. This will not interfere with 49 * the working directory (if there is one). 50 */ 51 int inmemory; 52 53 /** 54 * Used by `git_rebase_finish`, this is the name of the notes reference 55 * used to rewrite notes for rebased commits when finishing the rebase; 56 * if NULL, the contents of the configuration option `notes.rewriteRef` 57 * is examined, unless the configuration option `notes.rewrite.rebase` 58 * is set to false. If `notes.rewriteRef` is also NULL, notes will 59 * not be rewritten. 60 */ 61 const char *rewrite_notes_ref; 62 63 /** 64 * Options to control how trees are merged during `git_rebase_next`. 65 */ 66 git_merge_options merge_options; 67 68 /** 69 * Options to control how files are written during `git_rebase_init`, 70 * `git_rebase_next` and `git_rebase_abort`. Note that a minimum 71 * strategy of `GIT_CHECKOUT_SAFE` is defaulted in `init` and `next`, 72 * and a minimum strategy of `GIT_CHECKOUT_FORCE` is defaulted in 73 * `abort` to match git semantics. 74 */ 75 git_checkout_options checkout_options; 76 77 /** 78 * If provided, this will be called with the commit content, allowing 79 * a signature to be added to the rebase commit. Can be skipped with 80 * GIT_PASSTHROUGH. If GIT_PASSTHROUGH is returned, a commit will be made 81 * without a signature. 82 * This field is only used when performing git_rebase_commit. 83 */ 84 git_commit_signing_cb signing_cb; 85 86 /** 87 * This will be passed to each of the callbacks in this struct 88 * as the last parameter. 89 */ 90 void *payload; 91 } git_rebase_options; 92 93 /** 94 * Type of rebase operation in-progress after calling `git_rebase_next`. 95 */ 96 typedef enum { 97 /** 98 * The given commit is to be cherry-picked. The client should commit 99 * the changes and continue if there are no conflicts. 100 */ 101 GIT_REBASE_OPERATION_PICK = 0, 102 103 /** 104 * The given commit is to be cherry-picked, but the client should prompt 105 * the user to provide an updated commit message. 106 */ 107 GIT_REBASE_OPERATION_REWORD, 108 109 /** 110 * The given commit is to be cherry-picked, but the client should stop 111 * to allow the user to edit the changes before committing them. 112 */ 113 GIT_REBASE_OPERATION_EDIT, 114 115 /** 116 * The given commit is to be squashed into the previous commit. The 117 * commit message will be merged with the previous message. 118 */ 119 GIT_REBASE_OPERATION_SQUASH, 120 121 /** 122 * The given commit is to be squashed into the previous commit. The 123 * commit message from this commit will be discarded. 124 */ 125 GIT_REBASE_OPERATION_FIXUP, 126 127 /** 128 * No commit will be cherry-picked. The client should run the given 129 * command and (if successful) continue. 130 */ 131 GIT_REBASE_OPERATION_EXEC, 132 } git_rebase_operation_t; 133 134 #define GIT_REBASE_OPTIONS_VERSION 1 135 #define GIT_REBASE_OPTIONS_INIT \ 136 { GIT_REBASE_OPTIONS_VERSION, 0, 0, NULL, GIT_MERGE_OPTIONS_INIT, \ 137 GIT_CHECKOUT_OPTIONS_INIT, NULL, NULL } 138 139 /** Indicates that a rebase operation is not (yet) in progress. */ 140 #define GIT_REBASE_NO_OPERATION SIZE_MAX 141 142 /** 143 * A rebase operation 144 * 145 * Describes a single instruction/operation to be performed during the 146 * rebase. 147 */ 148 typedef struct { 149 /** The type of rebase operation. */ 150 git_rebase_operation_t type; 151 152 /** 153 * The commit ID being cherry-picked. This will be populated for 154 * all operations except those of type `GIT_REBASE_OPERATION_EXEC`. 155 */ 156 const git_oid id; 157 158 /** 159 * The executable the user has requested be run. This will only 160 * be populated for operations of type `GIT_REBASE_OPERATION_EXEC`. 161 */ 162 const char *exec; 163 } git_rebase_operation; 164 165 /** 166 * Initialize git_rebase_options structure 167 * 168 * Initializes a `git_rebase_options` with default values. Equivalent to 169 * creating an instance with `GIT_REBASE_OPTIONS_INIT`. 170 * 171 * @param opts The `git_rebase_options` struct to initialize. 172 * @param version The struct version; pass `GIT_REBASE_OPTIONS_VERSION`. 173 * @return Zero on success; -1 on failure. 174 */ 175 GIT_EXTERN(int) git_rebase_options_init( 176 git_rebase_options *opts, 177 unsigned int version); 178 179 /** 180 * Initializes a rebase operation to rebase the changes in `branch` 181 * relative to `upstream` onto another branch. To begin the rebase 182 * process, call `git_rebase_next`. When you have finished with this 183 * object, call `git_rebase_free`. 184 * 185 * @param out Pointer to store the rebase object 186 * @param repo The repository to perform the rebase 187 * @param branch The terminal commit to rebase, or NULL to rebase the 188 * current branch 189 * @param upstream The commit to begin rebasing from, or NULL to rebase all 190 * reachable commits 191 * @param onto The branch to rebase onto, or NULL to rebase onto the given 192 * upstream 193 * @param opts Options to specify how rebase is performed, or NULL 194 * @return Zero on success; -1 on failure. 195 */ 196 GIT_EXTERN(int) git_rebase_init( 197 git_rebase **out, 198 git_repository *repo, 199 const git_annotated_commit *branch, 200 const git_annotated_commit *upstream, 201 const git_annotated_commit *onto, 202 const git_rebase_options *opts); 203 204 /** 205 * Opens an existing rebase that was previously started by either an 206 * invocation of `git_rebase_init` or by another client. 207 * 208 * @param out Pointer to store the rebase object 209 * @param repo The repository that has a rebase in-progress 210 * @param opts Options to specify how rebase is performed 211 * @return Zero on success; -1 on failure. 212 */ 213 GIT_EXTERN(int) git_rebase_open( 214 git_rebase **out, 215 git_repository *repo, 216 const git_rebase_options *opts); 217 218 /** 219 * Gets the original `HEAD` ref name for merge rebases. 220 * 221 * @return The original `HEAD` ref name 222 */ 223 GIT_EXTERN(const char *) git_rebase_orig_head_name(git_rebase *rebase); 224 225 /** 226 * Gets the original `HEAD` id for merge rebases. 227 * 228 * @return The original `HEAD` id 229 */ 230 GIT_EXTERN(const git_oid *) git_rebase_orig_head_id(git_rebase *rebase); 231 232 /** 233 * Gets the `onto` ref name for merge rebases. 234 * 235 * @return The `onto` ref name 236 */ 237 GIT_EXTERN(const char *) git_rebase_onto_name(git_rebase *rebase); 238 239 /** 240 * Gets the `onto` id for merge rebases. 241 * 242 * @return The `onto` id 243 */ 244 GIT_EXTERN(const git_oid *) git_rebase_onto_id(git_rebase *rebase); 245 246 /** 247 * Gets the count of rebase operations that are to be applied. 248 * 249 * @param rebase The in-progress rebase 250 * @return The number of rebase operations in total 251 */ 252 GIT_EXTERN(size_t) git_rebase_operation_entrycount(git_rebase *rebase); 253 254 /** 255 * Gets the index of the rebase operation that is currently being applied. 256 * If the first operation has not yet been applied (because you have 257 * called `init` but not yet `next`) then this returns 258 * `GIT_REBASE_NO_OPERATION`. 259 * 260 * @param rebase The in-progress rebase 261 * @return The index of the rebase operation currently being applied. 262 */ 263 GIT_EXTERN(size_t) git_rebase_operation_current(git_rebase *rebase); 264 265 /** 266 * Gets the rebase operation specified by the given index. 267 * 268 * @param rebase The in-progress rebase 269 * @param idx The index of the rebase operation to retrieve 270 * @return The rebase operation or NULL if `idx` was out of bounds 271 */ 272 GIT_EXTERN(git_rebase_operation *) git_rebase_operation_byindex( 273 git_rebase *rebase, 274 size_t idx); 275 276 /** 277 * Performs the next rebase operation and returns the information about it. 278 * If the operation is one that applies a patch (which is any operation except 279 * GIT_REBASE_OPERATION_EXEC) then the patch will be applied and the index and 280 * working directory will be updated with the changes. If there are conflicts, 281 * you will need to address those before committing the changes. 282 * 283 * @param operation Pointer to store the rebase operation that is to be performed next 284 * @param rebase The rebase in progress 285 * @return Zero on success; -1 on failure. 286 */ 287 GIT_EXTERN(int) git_rebase_next( 288 git_rebase_operation **operation, 289 git_rebase *rebase); 290 291 /** 292 * Gets the index produced by the last operation, which is the result 293 * of `git_rebase_next` and which will be committed by the next 294 * invocation of `git_rebase_commit`. This is useful for resolving 295 * conflicts in an in-memory rebase before committing them. You must 296 * call `git_index_free` when you are finished with this. 297 * 298 * This is only applicable for in-memory rebases; for rebases within 299 * a working directory, the changes were applied to the repository's 300 * index. 301 */ 302 GIT_EXTERN(int) git_rebase_inmemory_index( 303 git_index **index, 304 git_rebase *rebase); 305 306 /** 307 * Commits the current patch. You must have resolved any conflicts that 308 * were introduced during the patch application from the `git_rebase_next` 309 * invocation. 310 * 311 * @param id Pointer in which to store the OID of the newly created commit 312 * @param rebase The rebase that is in-progress 313 * @param author The author of the updated commit, or NULL to keep the 314 * author from the original commit 315 * @param committer The committer of the rebase 316 * @param message_encoding The encoding for the message in the commit, 317 * represented with a standard encoding name. If message is NULL, 318 * this should also be NULL, and the encoding from the original 319 * commit will be maintained. If message is specified, this may be 320 * NULL to indicate that "UTF-8" is to be used. 321 * @param message The message for this commit, or NULL to use the message 322 * from the original commit. 323 * @return Zero on success, GIT_EUNMERGED if there are unmerged changes in 324 * the index, GIT_EAPPLIED if the current commit has already 325 * been applied to the upstream and there is nothing to commit, 326 * -1 on failure. 327 */ 328 GIT_EXTERN(int) git_rebase_commit( 329 git_oid *id, 330 git_rebase *rebase, 331 const git_signature *author, 332 const git_signature *committer, 333 const char *message_encoding, 334 const char *message); 335 336 /** 337 * Aborts a rebase that is currently in progress, resetting the repository 338 * and working directory to their state before rebase began. 339 * 340 * @param rebase The rebase that is in-progress 341 * @return Zero on success; GIT_ENOTFOUND if a rebase is not in progress, 342 * -1 on other errors. 343 */ 344 GIT_EXTERN(int) git_rebase_abort(git_rebase *rebase); 345 346 /** 347 * Finishes a rebase that is currently in progress once all patches have 348 * been applied. 349 * 350 * @param rebase The rebase that is in-progress 351 * @param signature The identity that is finishing the rebase (optional) 352 * @return Zero on success; -1 on error 353 */ 354 GIT_EXTERN(int) git_rebase_finish( 355 git_rebase *rebase, 356 const git_signature *signature); 357 358 /** 359 * Frees the `git_rebase` object. 360 * 361 * @param rebase The rebase object 362 */ 363 GIT_EXTERN(void) git_rebase_free(git_rebase *rebase); 364 365 /** @} */ 366 GIT_END_DECL 367 #endif 368