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_reflog_h__ 8 #define INCLUDE_git_reflog_h__ 9 10 #include "common.h" 11 #include "types.h" 12 #include "oid.h" 13 14 /** 15 * @file git2/reflog.h 16 * @brief Git reflog management routines 17 * @defgroup git_reflog Git reflog management routines 18 * @ingroup Git 19 * @{ 20 */ 21 GIT_BEGIN_DECL 22 23 /** 24 * Read the reflog for the given reference 25 * 26 * If there is no reflog file for the given 27 * reference yet, an empty reflog object will 28 * be returned. 29 * 30 * The reflog must be freed manually by using 31 * git_reflog_free(). 32 * 33 * @param out pointer to reflog 34 * @param repo the repostiory 35 * @param name reference to look up 36 * @return 0 or an error code 37 */ 38 GIT_EXTERN(int) git_reflog_read(git_reflog **out, git_repository *repo, const char *name); 39 40 /** 41 * Write an existing in-memory reflog object back to disk 42 * using an atomic file lock. 43 * 44 * @param reflog an existing reflog object 45 * @return 0 or an error code 46 */ 47 GIT_EXTERN(int) git_reflog_write(git_reflog *reflog); 48 49 /** 50 * Add a new entry to the in-memory reflog. 51 * 52 * `msg` is optional and can be NULL. 53 * 54 * @param reflog an existing reflog object 55 * @param id the OID the reference is now pointing to 56 * @param committer the signature of the committer 57 * @param msg the reflog message 58 * @return 0 or an error code 59 */ 60 GIT_EXTERN(int) git_reflog_append(git_reflog *reflog, const git_oid *id, const git_signature *committer, const char *msg); 61 62 /** 63 * Rename a reflog 64 * 65 * The reflog to be renamed is expected to already exist 66 * 67 * The new name will be checked for validity. 68 * See `git_reference_create_symbolic()` for rules about valid names. 69 * 70 * @param repo the repository 71 * @param old_name the old name of the reference 72 * @param name the new name of the reference 73 * @return 0 on success, GIT_EINVALIDSPEC or an error code 74 */ 75 GIT_EXTERN(int) git_reflog_rename(git_repository *repo, const char *old_name, const char *name); 76 77 /** 78 * Delete the reflog for the given reference 79 * 80 * @param repo the repository 81 * @param name the reflog to delete 82 * @return 0 or an error code 83 */ 84 GIT_EXTERN(int) git_reflog_delete(git_repository *repo, const char *name); 85 86 /** 87 * Get the number of log entries in a reflog 88 * 89 * @param reflog the previously loaded reflog 90 * @return the number of log entries 91 */ 92 GIT_EXTERN(size_t) git_reflog_entrycount(git_reflog *reflog); 93 94 /** 95 * Lookup an entry by its index 96 * 97 * Requesting the reflog entry with an index of 0 (zero) will 98 * return the most recently created entry. 99 * 100 * @param reflog a previously loaded reflog 101 * @param idx the position of the entry to lookup. Should be greater than or 102 * equal to 0 (zero) and less than `git_reflog_entrycount()`. 103 * @return the entry; NULL if not found 104 */ 105 GIT_EXTERN(const git_reflog_entry *) git_reflog_entry_byindex(const git_reflog *reflog, size_t idx); 106 107 /** 108 * Remove an entry from the reflog by its index 109 * 110 * To ensure there's no gap in the log history, set `rewrite_previous_entry` 111 * param value to 1. When deleting entry `n`, member old_oid of entry `n-1` 112 * (if any) will be updated with the value of member new_oid of entry `n+1`. 113 * 114 * @param reflog a previously loaded reflog. 115 * 116 * @param idx the position of the entry to remove. Should be greater than or 117 * equal to 0 (zero) and less than `git_reflog_entrycount()`. 118 * 119 * @param rewrite_previous_entry 1 to rewrite the history; 0 otherwise. 120 * 121 * @return 0 on success, GIT_ENOTFOUND if the entry doesn't exist 122 * or an error code. 123 */ 124 GIT_EXTERN(int) git_reflog_drop( 125 git_reflog *reflog, 126 size_t idx, 127 int rewrite_previous_entry); 128 129 /** 130 * Get the old oid 131 * 132 * @param entry a reflog entry 133 * @return the old oid 134 */ 135 GIT_EXTERN(const git_oid *) git_reflog_entry_id_old(const git_reflog_entry *entry); 136 137 /** 138 * Get the new oid 139 * 140 * @param entry a reflog entry 141 * @return the new oid at this time 142 */ 143 GIT_EXTERN(const git_oid *) git_reflog_entry_id_new(const git_reflog_entry *entry); 144 145 /** 146 * Get the committer of this entry 147 * 148 * @param entry a reflog entry 149 * @return the committer 150 */ 151 GIT_EXTERN(const git_signature *) git_reflog_entry_committer(const git_reflog_entry *entry); 152 153 /** 154 * Get the log message 155 * 156 * @param entry a reflog entry 157 * @return the log msg 158 */ 159 GIT_EXTERN(const char *) git_reflog_entry_message(const git_reflog_entry *entry); 160 161 /** 162 * Free the reflog 163 * 164 * @param reflog reflog to free 165 */ 166 GIT_EXTERN(void) git_reflog_free(git_reflog *reflog); 167 168 /** @} */ 169 GIT_END_DECL 170 #endif 171