include/git2/reflog.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007 #ifndef INCLUDE_git_reflog_h__
0008 #define INCLUDE_git_reflog_h__
0009
0010 #include "common.h"
0011 #include "types.h"
0012 #include "oid.h"
0013
0014 /**
0015  * @file git2/reflog.h
0016  * @brief Git reflog management routines
0017  * @defgroup git_reflog Git reflog management routines
0018  * @ingroup Git
0019  * @{
0020  */
0021 GIT_BEGIN_DECL
0022
0023 /**
0024  * Read the reflog for the given reference
0025  *
0026  * If there is no reflog file for the given
0027  * reference yet, an empty reflog object will
0028  * be returned.
0029  *
0030  * The reflog must be freed manually by using
0031  * git_reflog_free().
0032  *
0033  * @param out pointer to reflog
0034  * @param repo the repository
0035  * @param name reference to look up
0036  * @return 0 or an error code
0037  */
0038 GIT_EXTERN(int) git_reflog_read(git_reflog **out, git_repository *repo,  const char *name);
0039
0040 /**
0041  * Write an existing in-memory reflog object back to disk
0042  * using an atomic file lock.
0043  *
0044  * @param reflog an existing reflog object
0045  * @return 0 or an error code
0046  */
0047 GIT_EXTERN(int) git_reflog_write(git_reflog *reflog);
0048
0049 /**
0050  * Add a new entry to the in-memory reflog.
0051  *
0052  * `msg` is optional and can be NULL.
0053  *
0054  * @param reflog an existing reflog object
0055  * @param id the OID the reference is now pointing to
0056  * @param committer the signature of the committer
0057  * @param msg the reflog message
0058  * @return 0 or an error code
0059  */
0060 GIT_EXTERN(int) git_reflog_append(git_reflog *reflog, const git_oid *id, const git_signature *committer, const char *msg);
0061
0062 /**
0063  * Rename a reflog
0064  *
0065  * The reflog to be renamed is expected to already exist
0066  *
0067  * The new name will be checked for validity.
0068  * See `git_reference_create_symbolic()` for rules about valid names.
0069  *
0070  * @param repo the repository
0071  * @param old_name the old name of the reference
0072  * @param name the new name of the reference
0073  * @return 0 on success, GIT_EINVALIDSPEC or an error code
0074  */
0075 GIT_EXTERN(int) git_reflog_rename(git_repository *repo, const char *old_name, const char *name);
0076
0077 /**
0078  * Delete the reflog for the given reference
0079  *
0080  * @param repo the repository
0081  * @param name the reflog to delete
0082  * @return 0 or an error code
0083  */
0084 GIT_EXTERN(int) git_reflog_delete(git_repository *repo, const char *name);
0085
0086 /**
0087  * Get the number of log entries in a reflog
0088  *
0089  * @param reflog the previously loaded reflog
0090  * @return the number of log entries
0091  */
0092 GIT_EXTERN(size_t) git_reflog_entrycount(git_reflog *reflog);
0093
0094 /**
0095  * Lookup an entry by its index
0096  *
0097  * Requesting the reflog entry with an index of 0 (zero) will
0098  * return the most recently created entry.
0099  *
0100  * @param reflog a previously loaded reflog
0101  * @param idx the position of the entry to lookup. Should be greater than or
0102  * equal to 0 (zero) and less than `git_reflog_entrycount()`.
0103  * @return the entry; NULL if not found
0104  */
0105 GIT_EXTERN(const git_reflog_entry *) git_reflog_entry_byindex(const git_reflog *reflog, size_t idx);
0106
0107 /**
0108  * Remove an entry from the reflog by its index
0109  *
0110  * To ensure there's no gap in the log history, set `rewrite_previous_entry`
0111  * param value to 1. When deleting entry `n`, member old_oid of entry `n-1`
0112  * (if any) will be updated with the value of member new_oid of entry `n+1`.
0113  *
0114  * @param reflog a previously loaded reflog.
0115  *
0116  * @param idx the position of the entry to remove. Should be greater than or
0117  * equal to 0 (zero) and less than `git_reflog_entrycount()`.
0118  *
0119  * @param rewrite_previous_entry 1 to rewrite the history; 0 otherwise.
0120  *
0121  * @return 0 on success, GIT_ENOTFOUND if the entry doesn't exist
0122  * or an error code.
0123  */
0124 GIT_EXTERN(int) git_reflog_drop(
0125     git_reflog *reflog,
0126     size_t idx,
0127     int rewrite_previous_entry);
0128
0129 /**
0130  * Get the old oid
0131  *
0132  * @param entry a reflog entry
0133  * @return the old oid
0134  */
0135 GIT_EXTERN(const git_oid *) git_reflog_entry_id_old(const git_reflog_entry *entry);
0136
0137 /**
0138  * Get the new oid
0139  *
0140  * @param entry a reflog entry
0141  * @return the new oid at this time
0142  */
0143 GIT_EXTERN(const git_oid *) git_reflog_entry_id_new(const git_reflog_entry *entry);
0144
0145 /**
0146  * Get the committer of this entry
0147  *
0148  * @param entry a reflog entry
0149  * @return the committer
0150  */
0151 GIT_EXTERN(const git_signature *) git_reflog_entry_committer(const git_reflog_entry *entry);
0152
0153 /**
0154  * Get the log message
0155  *
0156  * @param entry a reflog entry
0157  * @return the log msg
0158  */
0159 GIT_EXTERN(const char *) git_reflog_entry_message(const git_reflog_entry *entry);
0160
0161 /**
0162  * Free the reflog
0163  *
0164  * @param reflog reflog to free
0165  */
0166 GIT_EXTERN(void) git_reflog_free(git_reflog *reflog);
0167
0168 /** @} */
0169 GIT_END_DECL
0170 #endif