diff options
author | Carlos Martín Nieto <cmn@dwim.me> | 2014-07-03 08:19:03 +0400 |
---|---|---|
committer | Carlos Martín Nieto <cmn@dwim.me> | 2014-07-03 08:19:03 +0400 |
commit | 70cdc69cc9979545ba2ef1556fec9c60879ac613 (patch) | |
tree | 701e6fb592e64044d5ba6194556ec91ea5a7d86a | |
parent | 8384126293d76a49b905bd9320fbd3419aed50f2 (diff) |
transaction: add documentationcmn/reference-transaction
-rw-r--r-- | include/git2/transaction.h | 90 |
1 files changed, 88 insertions, 2 deletions
diff --git a/include/git2/transaction.h b/include/git2/transaction.h index 46f4cfba0..d5d7cb4cf 100644 --- a/include/git2/transaction.h +++ b/include/git2/transaction.h @@ -10,16 +10,102 @@ #include "common.h" GIT_BEGIN_DECL +/** + * Create a new transaction object + * + * This does not lock anything, but sets up the transaction object to + * know from which repository to lock. + * + * @param out the resulting transaction + * @param repo the repository in which to lock + * @return 0 or an error code + */ GIT_EXTERN(int) git_transaction_new(git_transaction **out, git_repository *repo); + +/** + * Lock a reference + * + * Lock the specified reference. This is the first step to updating a + * reference. + * + * @param tx the transaction + * @param refname the reference to lock + * @return 0 or an error message + */ GIT_EXTERN(int) git_transaction_lock(git_transaction *tx, const char *refname); + +/** + * Set the target of a reference + * + * Set the target of the specified reference. This reference must be + * locked. + * + * @param tx the transaction + * @param refname reference to update + * @param target target to set the reference to + * @param sig signature to use in the reflog; pass NULL to read the identity from the config + * @param msg message to use in the reflog + * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code + */ GIT_EXTERN(int) git_transaction_set_target(git_transaction *tx, const char *refname, const git_oid *target, const git_signature *sig, const char *msg); +/** + * Set the target of a reference + * + * Set the target of the specified reference. This reference must be + * locked. + * + * @param tx the transaction + * @param refname reference to update + * @param target target to set the reference to + * @param sig signature to use in the reflog; pass NULL to read the identity from the config + * @param msg message to use in the reflog + * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code + */ GIT_EXTERN(int) git_transaction_set_symbolic_target(git_transaction *tx, const char *refname, const char *target, const git_signature *sig, const char *msg); + +/** + * Set the reflog of a reference + * + * Set the specified reference's reflog. If this is combined with + * setting the target, that update won't be written to the reflog. + * + * @param tx the transaction + * @param refname the reference whose reflog to set + * @param reflog the reflog as it should be written out + * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code + */ GIT_EXTERN(int) git_transaction_set_reflog(git_transaction *tx, const char *refname, const git_reflog *reflog); -GIT_EXTERN(int) git_transaction_commit(git_transaction *tx); -GIT_EXTERN(void) git_transaction_free(git_transaction *tx); + +/** + * Remove a reference + * + * @param tx the transaction + * @param refname the reference to remove + * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code + */ GIT_EXTERN(int) git_transaction_remove(git_transaction *tx, const char *refname); +/** + * Commit the changes from the transaction + * + * Perform the changes that have been queued. The updates will be made + * one by one, and the first failure will stop the processing. + * + * @param tx the transaction + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transaction_commit(git_transaction *tx); + +/** + * Free the resources allocated by this transaction + * + * If any references remain locked, they will be unlocked without any + * changes made to them. + * + * @param tx the transaction + */ +GIT_EXTERN(void) git_transaction_free(git_transaction *tx); GIT_END_DECL #endif |