include/git2/transaction.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_transaction_h__
   8 #define INCLUDE_git_transaction_h__
   9
  10 #include "common.h"
  11
  12 /**
  13  * @file git2/transaction.h
  14  * @brief Git transactional reference routines
  15  * @defgroup git_transaction Git transactional reference routines
  16  * @ingroup Git
  17  * @{
  18  */
  19 GIT_BEGIN_DECL
  20
  21 /**
  22  * Create a new transaction object
  23  *
  24  * This does not lock anything, but sets up the transaction object to
  25  * know from which repository to lock.
  26  *
  27  * @param out the resulting transaction
  28  * @param repo the repository in which to lock
  29  * @return 0 or an error code
  30  */
  31 GIT_EXTERN(int) git_transaction_new(git_transaction **out, git_repository *repo);
  32
  33 /**
  34  * Lock a reference
  35  *
  36  * Lock the specified reference. This is the first step to updating a
  37  * reference.
  38  *
  39  * @param tx the transaction
  40  * @param refname the reference to lock
  41  * @return 0 or an error message
  42  */
  43 GIT_EXTERN(int) git_transaction_lock_ref(git_transaction *tx, const char *refname);
  44
  45 /**
  46  * Set the target of a reference
  47  *
  48  * Set the target of the specified reference. This reference must be
  49  * locked.
  50  *
  51  * @param tx the transaction
  52  * @param refname reference to update
  53  * @param target target to set the reference to
  54  * @param sig signature to use in the reflog; pass NULL to read the identity from the config
  55  * @param msg message to use in the reflog
  56  * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code
  57  */
  58 GIT_EXTERN(int) git_transaction_set_target(git_transaction *tx, const char *refname, const git_oid *target, const git_signature *sig, const char *msg);
  59
  60 /**
  61  * Set the target of a reference
  62  *
  63  * Set the target of the specified reference. This reference must be
  64  * locked.
  65  *
  66  * @param tx the transaction
  67  * @param refname reference to update
  68  * @param target target to set the reference to
  69  * @param sig signature to use in the reflog; pass NULL to read the identity from the config
  70  * @param msg message to use in the reflog
  71  * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code
  72  */
  73 GIT_EXTERN(int) git_transaction_set_symbolic_target(git_transaction *tx, const char *refname, const char *target, const git_signature *sig, const char *msg);
  74
  75 /**
  76  * Set the reflog of a reference
  77  *
  78  * Set the specified reference's reflog. If this is combined with
  79  * setting the target, that update won't be written to the reflog.
  80  *
  81  * @param tx the transaction
  82  * @param refname the reference whose reflog to set
  83  * @param reflog the reflog as it should be written out
  84  * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code
  85  */
  86 GIT_EXTERN(int) git_transaction_set_reflog(git_transaction *tx, const char *refname, const git_reflog *reflog);
  87
  88 /**
  89  * Remove a reference
  90  *
  91  * @param tx the transaction
  92  * @param refname the reference to remove
  93  * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code
  94  */
  95 GIT_EXTERN(int) git_transaction_remove(git_transaction *tx, const char *refname);
  96
  97 /**
  98  * Commit the changes from the transaction
  99  *
 100  * Perform the changes that have been queued. The updates will be made
 101  * one by one, and the first failure will stop the processing.
 102  *
 103  * @param tx the transaction
 104  * @return 0 or an error code
 105  */
 106 GIT_EXTERN(int) git_transaction_commit(git_transaction *tx);
 107
 108 /**
 109  * Free the resources allocated by this transaction
 110  *
 111  * If any references remain locked, they will be unlocked without any
 112  * changes made to them.
 113  *
 114  * @param tx the transaction
 115  */
 116 GIT_EXTERN(void) git_transaction_free(git_transaction *tx);
 117
 118 /** @} */
 119 GIT_END_DECL
 120 #endif