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 * Optional callback that allows users to override commit 79 * creation in `git_rebase_commit`. If specified, users can 80 * create their own commit and provide the commit ID, which 81 * may be useful for signing commits or otherwise customizing 82 * the commit creation. 83 * 84 * If this callback returns `GIT_PASSTHROUGH`, then 85 * `git_rebase_commit` will continue to create the commit. 86 */ 87 git_commit_create_cb commit_create_cb; 88 89 #ifdef GIT_DEPRECATE_HARD 90 void *reserved; 91 #else 92 /** 93 * If provided, this will be called with the commit content, allowing 94 * a signature to be added to the rebase commit. Can be skipped with 95 * GIT_PASSTHROUGH. If GIT_PASSTHROUGH is returned, a commit will be made 96 * without a signature. 97 * 98 * This field is only used when performing git_rebase_commit. 99 * 100 * This callback is not invoked if a `git_commit_create_cb` is 101 * specified. 102 * 103 * This callback is deprecated; users should provide a 104 * creation callback as `commit_create_cb` that produces a 105 * commit buffer, signs it, and commits it. 106 */ 107 int (*signing_cb)(git_buf *, git_buf *, const char *, void *); 108 #endif 109 110 /** 111 * This will be passed to each of the callbacks in this struct 112 * as the last parameter. 113 */ 114 void *payload; 115 } git_rebase_options; 116 117 /** 118 * Type of rebase operation in-progress after calling `git_rebase_next`. 119 */ 120 typedef enum { 121 /** 122 * The given commit is to be cherry-picked. The client should commit 123 * the changes and continue if there are no conflicts. 124 */ 125 GIT_REBASE_OPERATION_PICK = 0, 126 127 /** 128 * The given commit is to be cherry-picked, but the client should prompt 129 * the user to provide an updated commit message. 130 */ 131 GIT_REBASE_OPERATION_REWORD, 132 133 /** 134 * The given commit is to be cherry-picked, but the client should stop 135 * to allow the user to edit the changes before committing them. 136 */ 137 GIT_REBASE_OPERATION_EDIT, 138 139 /** 140 * The given commit is to be squashed into the previous commit. The 141 * commit message will be merged with the previous message. 142 */ 143 GIT_REBASE_OPERATION_SQUASH, 144 145 /** 146 * The given commit is to be squashed into the previous commit. The 147 * commit message from this commit will be discarded. 148 */ 149 GIT_REBASE_OPERATION_FIXUP, 150 151 /** 152 * No commit will be cherry-picked. The client should run the given 153 * command and (if successful) continue. 154 */ 155 GIT_REBASE_OPERATION_EXEC, 156 } git_rebase_operation_t; 157 158 #define GIT_REBASE_OPTIONS_VERSION 1 159 #define GIT_REBASE_OPTIONS_INIT \ 160 { GIT_REBASE_OPTIONS_VERSION, 0, 0, NULL, GIT_MERGE_OPTIONS_INIT, \ 161 GIT_CHECKOUT_OPTIONS_INIT, NULL, NULL } 162 163 /** Indicates that a rebase operation is not (yet) in progress. */ 164 #define GIT_REBASE_NO_OPERATION SIZE_MAX 165 166 /** 167 * A rebase operation 168 * 169 * Describes a single instruction/operation to be performed during the 170 * rebase. 171 */ 172 typedef struct { 173 /** The type of rebase operation. */ 174 git_rebase_operation_t type; 175 176 /** 177 * The commit ID being cherry-picked. This will be populated for 178 * all operations except those of type `GIT_REBASE_OPERATION_EXEC`. 179 */ 180 const git_oid id; 181 182 /** 183 * The executable the user has requested be run. This will only 184 * be populated for operations of type `GIT_REBASE_OPERATION_EXEC`. 185 */ 186 const char *exec; 187 } git_rebase_operation; 188 189 /** 190 * Initialize git_rebase_options structure 191 * 192 * Initializes a `git_rebase_options` with default values. Equivalent to 193 * creating an instance with `GIT_REBASE_OPTIONS_INIT`. 194 * 195 * @param opts The `git_rebase_options` struct to initialize. 196 * @param version The struct version; pass `GIT_REBASE_OPTIONS_VERSION`. 197 * @return Zero on success; -1 on failure. 198 */ 199 GIT_EXTERN(int) git_rebase_options_init( 200 git_rebase_options *opts, 201 unsigned int version); 202 203 /** 204 * Initializes a rebase operation to rebase the changes in `branch` 205 * relative to `upstream` onto another branch. To begin the rebase 206 * process, call `git_rebase_next`. When you have finished with this 207 * object, call `git_rebase_free`. 208 * 209 * @param out Pointer to store the rebase object 210 * @param repo The repository to perform the rebase 211 * @param branch The terminal commit to rebase, or NULL to rebase the 212 * current branch 213 * @param upstream The commit to begin rebasing from, or NULL to rebase all 214 * reachable commits 215 * @param onto The branch to rebase onto, or NULL to rebase onto the given 216 * upstream 217 * @param opts Options to specify how rebase is performed, or NULL 218 * @return Zero on success; -1 on failure. 219 */ 220 GIT_EXTERN(int) git_rebase_init( 221 git_rebase **out, 222 git_repository *repo, 223 const git_annotated_commit *branch, 224 const git_annotated_commit *upstream, 225 const git_annotated_commit *onto, 226 const git_rebase_options *opts); 227 228 /** 229 * Opens an existing rebase that was previously started by either an 230 * invocation of `git_rebase_init` or by another client. 231 * 232 * @param out Pointer to store the rebase object 233 * @param repo The repository that has a rebase in-progress 234 * @param opts Options to specify how rebase is performed 235 * @return Zero on success; -1 on failure. 236 */ 237 GIT_EXTERN(int) git_rebase_open( 238 git_rebase **out, 239 git_repository *repo, 240 const git_rebase_options *opts); 241 242 /** 243 * Gets the original `HEAD` ref name for merge rebases. 244 * 245 * @return The original `HEAD` ref name 246 */ 247 GIT_EXTERN(const char *) git_rebase_orig_head_name(git_rebase *rebase); 248 249 /** 250 * Gets the original `HEAD` id for merge rebases. 251 * 252 * @return The original `HEAD` id 253 */ 254 GIT_EXTERN(const git_oid *) git_rebase_orig_head_id(git_rebase *rebase); 255 256 /** 257 * Gets the `onto` ref name for merge rebases. 258 * 259 * @return The `onto` ref name 260 */ 261 GIT_EXTERN(const char *) git_rebase_onto_name(git_rebase *rebase); 262 263 /** 264 * Gets the `onto` id for merge rebases. 265 * 266 * @return The `onto` id 267 */ 268 GIT_EXTERN(const git_oid *) git_rebase_onto_id(git_rebase *rebase); 269 270 /** 271 * Gets the count of rebase operations that are to be applied. 272 * 273 * @param rebase The in-progress rebase 274 * @return The number of rebase operations in total 275 */ 276 GIT_EXTERN(size_t) git_rebase_operation_entrycount(git_rebase *rebase); 277 278 /** 279 * Gets the index of the rebase operation that is currently being applied. 280 * If the first operation has not yet been applied (because you have 281 * called `init` but not yet `next`) then this returns 282 * `GIT_REBASE_NO_OPERATION`. 283 * 284 * @param rebase The in-progress rebase 285 * @return The index of the rebase operation currently being applied. 286 */ 287 GIT_EXTERN(size_t) git_rebase_operation_current(git_rebase *rebase); 288 289 /** 290 * Gets the rebase operation specified by the given index. 291 * 292 * @param rebase The in-progress rebase 293 * @param idx The index of the rebase operation to retrieve 294 * @return The rebase operation or NULL if `idx` was out of bounds 295 */ 296 GIT_EXTERN(git_rebase_operation *) git_rebase_operation_byindex( 297 git_rebase *rebase, 298 size_t idx); 299 300 /** 301 * Performs the next rebase operation and returns the information about it. 302 * If the operation is one that applies a patch (which is any operation except 303 * GIT_REBASE_OPERATION_EXEC) then the patch will be applied and the index and 304 * working directory will be updated with the changes. If there are conflicts, 305 * you will need to address those before committing the changes. 306 * 307 * @param operation Pointer to store the rebase operation that is to be performed next 308 * @param rebase The rebase in progress 309 * @return Zero on success; -1 on failure. 310 */ 311 GIT_EXTERN(int) git_rebase_next( 312 git_rebase_operation **operation, 313 git_rebase *rebase); 314 315 /** 316 * Gets the index produced by the last operation, which is the result 317 * of `git_rebase_next` and which will be committed by the next 318 * invocation of `git_rebase_commit`. This is useful for resolving 319 * conflicts in an in-memory rebase before committing them. You must 320 * call `git_index_free` when you are finished with this. 321 * 322 * This is only applicable for in-memory rebases; for rebases within 323 * a working directory, the changes were applied to the repository's 324 * index. 325 */ 326 GIT_EXTERN(int) git_rebase_inmemory_index( 327 git_index **index, 328 git_rebase *rebase); 329 330 /** 331 * Commits the current patch. You must have resolved any conflicts that 332 * were introduced during the patch application from the `git_rebase_next` 333 * invocation. 334 * 335 * @param id Pointer in which to store the OID of the newly created commit 336 * @param rebase The rebase that is in-progress 337 * @param author The author of the updated commit, or NULL to keep the 338 * author from the original commit 339 * @param committer The committer of the rebase 340 * @param message_encoding The encoding for the message in the commit, 341 * represented with a standard encoding name. If message is NULL, 342 * this should also be NULL, and the encoding from the original 343 * commit will be maintained. If message is specified, this may be 344 * NULL to indicate that "UTF-8" is to be used. 345 * @param message The message for this commit, or NULL to use the message 346 * from the original commit. 347 * @return Zero on success, GIT_EUNMERGED if there are unmerged changes in 348 * the index, GIT_EAPPLIED if the current commit has already 349 * been applied to the upstream and there is nothing to commit, 350 * -1 on failure. 351 */ 352 GIT_EXTERN(int) git_rebase_commit( 353 git_oid *id, 354 git_rebase *rebase, 355 const git_signature *author, 356 const git_signature *committer, 357 const char *message_encoding, 358 const char *message); 359 360 /** 361 * Aborts a rebase that is currently in progress, resetting the repository 362 * and working directory to their state before rebase began. 363 * 364 * @param rebase The rebase that is in-progress 365 * @return Zero on success; GIT_ENOTFOUND if a rebase is not in progress, 366 * -1 on other errors. 367 */ 368 GIT_EXTERN(int) git_rebase_abort(git_rebase *rebase); 369 370 /** 371 * Finishes a rebase that is currently in progress once all patches have 372 * been applied. 373 * 374 * @param rebase The rebase that is in-progress 375 * @param signature The identity that is finishing the rebase (optional) 376 * @return Zero on success; -1 on error 377 */ 378 GIT_EXTERN(int) git_rebase_finish( 379 git_rebase *rebase, 380 const git_signature *signature); 381 382 /** 383 * Frees the `git_rebase` object. 384 * 385 * @param rebase The rebase object 386 */ 387 GIT_EXTERN(void) git_rebase_free(git_rebase *rebase); 388 389 /** @} */ 390 GIT_END_DECL 391 #endif 392