diff options
Diffstat (limited to 'include/git2/reflog.h')
| -rw-r--r-- | include/git2/reflog.h | 83 |
1 files changed, 61 insertions, 22 deletions
diff --git a/include/git2/reflog.h b/include/git2/reflog.h index f490e29de..4944530af 100644 --- a/include/git2/reflog.h +++ b/include/git2/reflog.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2009-2012 the libgit2 contributors + * Copyright (C) the libgit2 contributors. All rights reserved. * * This file is part of libgit2, distributed under the GNU GPL v2 with * a Linking Exception. For full terms see the included COPYING file. @@ -23,41 +23,54 @@ GIT_BEGIN_DECL /** * Read the reflog for the given reference * + * If there is no reflog file for the given + * reference yet, an empty reflog object will + * be returned. + * * The reflog must be freed manually by using * git_reflog_free(). * - * @param reflog pointer to reflog + * @param out pointer to reflog * @param ref reference to read the reflog for * @return 0 or an error code */ -GIT_EXTERN(int) git_reflog_read(git_reflog **reflog, git_reference *ref); +GIT_EXTERN(int) git_reflog_read(git_reflog **out, const git_reference *ref); /** - * Write a new reflog for the given reference + * Write an existing in-memory reflog object back to disk + * using an atomic file lock. * - * If there is no reflog file for the given - * reference yet, it will be created. - * - * `oid_old` may be NULL in case it's a new reference. + * @param reflog an existing reflog object + * @return 0 or an error code + */ +GIT_EXTERN(int) git_reflog_write(git_reflog *reflog); + +/** + * Add a new entry to the reflog. * * `msg` is optional and can be NULL. * - * @param ref the changed reference - * @param oid_old the OID the reference was pointing to + * @param reflog an existing reflog object + * @param id the OID the reference is now pointing to * @param committer the signature of the committer * @param msg the reflog message * @return 0 or an error code */ -GIT_EXTERN(int) git_reflog_write(git_reference *ref, const git_oid *oid_old, const git_signature *committer, const char *msg); +GIT_EXTERN(int) git_reflog_append(git_reflog *reflog, const git_oid *id, const git_signature *committer, const char *msg); /** * Rename the reflog for the given reference * + * The reflog to be renamed is expected to already exist + * + * The new name will be checked for validity. + * See `git_reference_create_symbolic()` for rules about valid names. + * * @param ref the reference - * @param new_name the new name of the reference - * @return 0 or an error code + * @param name the new name of the reference + * @return 0 on success, GIT_EINVALIDSPEC or an error code */ -GIT_EXTERN(int) git_reflog_rename(git_reference *ref, const char *new_name); +GIT_EXTERN(int) git_reflog_rename(git_reference *ref, const char *name); /** * Delete the reflog for the given reference @@ -73,16 +86,42 @@ GIT_EXTERN(int) git_reflog_delete(git_reference *ref); * @param reflog the previously loaded reflog * @return the number of log entries */ -GIT_EXTERN(unsigned int) git_reflog_entrycount(git_reflog *reflog); +GIT_EXTERN(size_t) git_reflog_entrycount(git_reflog *reflog); /** * Lookup an entry by its index * + * Requesting the reflog entry with an index of 0 (zero) will + * return the most recently created entry. + * * @param reflog a previously loaded reflog - * @param idx the position to lookup + * @param idx the position of the entry to lookup. Should be greater than or + * equal to 0 (zero) and less than `git_reflog_entrycount()`. * @return the entry; NULL if not found */ -GIT_EXTERN(const git_reflog_entry *) git_reflog_entry_byindex(git_reflog *reflog, unsigned int idx); +GIT_EXTERN(const git_reflog_entry *) git_reflog_entry_byindex(git_reflog *reflog, size_t idx); + +/** + * Remove an entry from the reflog by its index + * + * To ensure there's no gap in the log history, set `rewrite_previous_entry` + * param value to 1. When deleting entry `n`, member old_oid of entry `n-1` + * (if any) will be updated with the value of member new_oid of entry `n+1`. + * + * @param reflog a previously loaded reflog. + * + * @param idx the position of the entry to remove. Should be greater than or + * equal to 0 (zero) and less than `git_reflog_entrycount()`. + * + * @param rewrite_previous_entry 1 to rewrite the history; 0 otherwise. + * + * @return 0 on success, GIT_ENOTFOUND if the entry doesn't exist + * or an error code. + */ +GIT_EXTERN(int) git_reflog_drop( + git_reflog *reflog, + size_t idx, + int rewrite_previous_entry); /** * Get the old oid @@ -90,7 +129,7 @@ GIT_EXTERN(const git_reflog_entry *) git_reflog_entry_byindex(git_reflog *reflog * @param entry a reflog entry * @return the old oid */ -GIT_EXTERN(const git_oid *) git_reflog_entry_oidold(const git_reflog_entry *entry); +GIT_EXTERN(const git_oid *) git_reflog_entry_id_old(const git_reflog_entry *entry); /** * Get the new oid @@ -98,7 +137,7 @@ GIT_EXTERN(const git_oid *) git_reflog_entry_oidold(const git_reflog_entry *entr * @param entry a reflog entry * @return the new oid at this time */ -GIT_EXTERN(const git_oid *) git_reflog_entry_oidnew(const git_reflog_entry *entry); +GIT_EXTERN(const git_oid *) git_reflog_entry_id_new(const git_reflog_entry *entry); /** * Get the committer of this entry @@ -106,15 +145,15 @@ GIT_EXTERN(const git_oid *) git_reflog_entry_oidnew(const git_reflog_entry *entr * @param entry a reflog entry * @return the committer */ -GIT_EXTERN(git_signature *) git_reflog_entry_committer(const git_reflog_entry *entry); +GIT_EXTERN(const git_signature *) git_reflog_entry_committer(const git_reflog_entry *entry); /** - * Get the log msg + * Get the log message * * @param entry a reflog entry * @return the log msg */ -GIT_EXTERN(char *) git_reflog_entry_msg(const git_reflog_entry *entry); +GIT_EXTERN(const char *) git_reflog_entry_message(const git_reflog_entry *entry); /** * Free the reflog |