include/git2/transaction.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_transaction_h__
0008 #define INCLUDE_git_transaction_h__
0009
0010 #include "common.h"
0011 #include "types.h"
0012
0013 /**
0014  * @file git2/transaction.h
0015  * @brief Git transactional reference routines
0016  * @defgroup git_transaction Git transactional reference routines
0017  * @ingroup Git
0018  * @{
0019  */
0020 GIT_BEGIN_DECL
0021
0022 /**
0023  * Create a new transaction object
0024  *
0025  * This does not lock anything, but sets up the transaction object to
0026  * know from which repository to lock.
0027  *
0028  * @param out the resulting transaction
0029  * @param repo the repository in which to lock
0030  * @return 0 or an error code
0031  */
0032 GIT_EXTERN(int) git_transaction_new(git_transaction **out, git_repository *repo);
0033
0034 /**
0035  * Lock a reference
0036  *
0037  * Lock the specified reference. This is the first step to updating a
0038  * reference.
0039  *
0040  * @param tx the transaction
0041  * @param refname the reference to lock
0042  * @return 0 or an error message
0043  */
0044 GIT_EXTERN(int) git_transaction_lock_ref(git_transaction *tx, const char *refname);
0045
0046 /**
0047  * Set the target of a reference
0048  *
0049  * Set the target of the specified reference. This reference must be
0050  * locked.
0051  *
0052  * @param tx the transaction
0053  * @param refname reference to update
0054  * @param target target to set the reference to
0055  * @param sig signature to use in the reflog; pass NULL to read the identity from the config
0056  * @param msg message to use in the reflog
0057  * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code
0058  */
0059 GIT_EXTERN(int) git_transaction_set_target(git_transaction *tx, const char *refname, const git_oid *target, const git_signature *sig, const char *msg);
0060
0061 /**
0062  * Set the target of a reference
0063  *
0064  * Set the target of the specified reference. This reference must be
0065  * locked.
0066  *
0067  * @param tx the transaction
0068  * @param refname reference to update
0069  * @param target target to set the reference to
0070  * @param sig signature to use in the reflog; pass NULL to read the identity from the config
0071  * @param msg message to use in the reflog
0072  * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code
0073  */
0074 GIT_EXTERN(int) git_transaction_set_symbolic_target(git_transaction *tx, const char *refname, const char *target, const git_signature *sig, const char *msg);
0075
0076 /**
0077  * Set the reflog of a reference
0078  *
0079  * Set the specified reference's reflog. If this is combined with
0080  * setting the target, that update won't be written to the reflog.
0081  *
0082  * @param tx the transaction
0083  * @param refname the reference whose reflog to set
0084  * @param reflog the reflog as it should be written out
0085  * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code
0086  */
0087 GIT_EXTERN(int) git_transaction_set_reflog(git_transaction *tx, const char *refname, const git_reflog *reflog);
0088
0089 /**
0090  * Remove a reference
0091  *
0092  * @param tx the transaction
0093  * @param refname the reference to remove
0094  * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code
0095  */
0096 GIT_EXTERN(int) git_transaction_remove(git_transaction *tx, const char *refname);
0097
0098 /**
0099  * Commit the changes from the transaction
0100  *
0101  * Perform the changes that have been queued. The updates will be made
0102  * one by one, and the first failure will stop the processing.
0103  *
0104  * @param tx the transaction
0105  * @return 0 or an error code
0106  */
0107 GIT_EXTERN(int) git_transaction_commit(git_transaction *tx);
0108
0109 /**
0110  * Free the resources allocated by this transaction
0111  *
0112  * If any references remain locked, they will be unlocked without any
0113  * changes made to them.
0114  *
0115  * @param tx the transaction
0116  */
0117 GIT_EXTERN(void) git_transaction_free(git_transaction *tx);
0118
0119 /** @} */
0120 GIT_END_DECL
0121 #endif