include/git2/reflog.h

   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 repository
  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