Skip to content

Commit 4938686

Browse files
dturner-twgitster
authored andcommitted
refs: document transaction semantics
Add some comments on ref transaction semantics to refs.h Signed-off-by: David Turner <[email protected]> Signed-off-by: Junio C Hamano <[email protected]>
1 parent 7548842 commit 4938686

File tree

1 file changed

+12
-0
lines changed

1 file changed

+12
-0
lines changed

refs.h

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,11 @@ extern int dwim_log(const char *str, int len, unsigned char *sha1, char **ref);
109109
* If this succeeds, the ref updates will have taken place and
110110
* the transaction cannot be rolled back.
111111
*
112+
* - Instead of `ref_transaction_commit`, use
113+
* `initial_ref_transaction_commit()` if the ref database is known
114+
* to be empty (e.g. during clone). This is likely to be much
115+
* faster.
116+
*
112117
* - At any time call `ref_transaction_free()` to discard the
113118
* transaction and free associated resources. In particular,
114119
* this rolls back the transaction if it has not been
@@ -124,6 +129,13 @@ extern int dwim_log(const char *str, int len, unsigned char *sha1, char **ref);
124129
*
125130
* The message is appended to err without first clearing err.
126131
* err will not be '\n' terminated.
132+
*
133+
* Caveats
134+
* -------
135+
*
136+
* Note that no locks are taken, and no refs are read, until
137+
* `ref_transaction_commit` is called. So `ref_transaction_verify`
138+
* won't report a verification failure until the commit is attempted.
127139
*/
128140
struct ref_transaction;
129141

0 commit comments

Comments
 (0)