branch: reset instead of release a strbuf

Our documentation advises to not re-use a strbuf, after strbuf_release has been called on it. Use the proper reset instead.

Signed-off-by Stefan Beller <[email protected]>

---

Maybe one of the #leftoverbits is to remove the re-init call in release and see what breaks? (And then fixing up more of such cases as presented in this patch)

 builtin/branch.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

builtin/branch.c +0 -0

index b998e16d0c..9758012390 100644

Our documentation advises to not re-use a strbuf, after strbuf_release has been called on it. Use the proper reset instead.

Reviewed-by Jonathan Nieder <[email protected]>

Signed-off-by Stefan Beller <[email protected]>

---
 builtin/branch.c | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

Here's a patch to address the surprising strbuf.h advice.

-- >8 --
Subject: strbuf: do not encourage init-after-release

strbuf_release already leaves the strbuf in a valid, initialized state, so there is not need to call strbuf_init after it.

Moreover, this is not likely to change in the future: strbuf_release leaving the strbuf in a valid state has been easy to maintain and has been very helpful for Git's robustness and simplicity (e.g., preventing use-after-free vulnerabilities).

It is still not advisable to call strbuf_release until done using a strbuf because it is wasteful, so keep that part of the advice.

Quoted 6 lines

/**
* Release a string buffer and the memory it used. You should not use the
- * string buffer after using this function, unless you initialize it again.
+ * string buffer after using this function.
*/
extern void strbuf_release(struct strbuf *);

I think it's actually OK to use the string buffer after this function. It's just an empty string.

Perhaps we should be more explicit: this releases any resources and resets to a pristine, empty state. I suspect strbuf_detach() probably should make the same claim.

Earlier you mentioned:

Quoted 2 lines

It is still not advisable to call strbuf_release until done using a strbuf because it is wasteful, so keep that part of the advice.

Is this what you meant? If so, I think we should probably be more explicit in giving people a hint to use strbuf_reset() for efficiency.

I think it's actually OK to use the string buffer after this function. It's just an empty string.

Perhaps we should be more explicit: this releases any resources and resets to a pristine, empty state. I suspect strbuf_detach() probably should make the same claim.

strbuf_release leaves the strbuf in a valid, initialized state, so there is no need to call strbuf_init after it.

Moreover, this is not likely to change in the future: strbuf_release leaving the strbuf in a valid state has been easy to maintain and has been very helpful for Git's robustness and simplicity (e.g., preventing use-after-free vulnerabilities).

Document the semantics so the next generation of Git developers can become familiar with them without reading the implementation. It is still not advisable to call strbuf_release too often because it is wasteful, so add a note pointing to strbuf_reset for that.

The same semantics apply to strbuf_detach. Add a similar note to its docstring to make that clear.

Improved-by Jeff King <[email protected]>

Signed-off-by Jonathan Nieder <[email protected]>

---
Jeff King wrote:

Quoted 6 lines

I think it's actually OK to use the string buffer after this function. It's just an empty string.

Perhaps we should be more explicit: this releases any resources and resets to a pristine, empty state. I suspect strbuf_detach() probably should make the same claim.

Like this?

Thanks,
Jonathan

 strbuf.h | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

strbuf.h +9 -2

index 7496cb8ec5..249df86711 100644
@@ -82,8 +82,12 @@ extern char strbuf_slopbuf[];
 extern void strbuf_init(struct strbuf *, size_t);
 
 /**
- * Release a string buffer and the memory it used. You should not use the
- * string buffer after using this function, unless you initialize it again.
+ * Release a string buffer and the memory it used. After this call, the
+ * strbuf points to an empty string that does not need to be free()ed, as
+ * if it had been set to `STRBUF_INIT` and never modified.
+ *
+ * To clear a strbuf in preparation for further use without the overhead
+ * of free()ing and malloc()ing again, use strbuf_reset() instead.
  */
 extern void strbuf_release(struct strbuf *);
 

@@ -91,6 +95,9 @@ extern void strbuf_release(struct strbuf *);
  * Detach the string from the strbuf and returns it; you now own the
  * storage the string occupies and it is your responsibility from then on
  * to release it with `free(3)` when you are done with it.
+ *
+ * The strbuf that previously held the string is reset to `STRBUF_INIT` so
+ * it can be reused after calling this function.
  */
 extern char *strbuf_detach(struct strbuf *, size_t *);

Quoted 6 lines

I think it's actually OK to use the string buffer after this function. It's just an empty string.

Perhaps we should be more explicit: this releases any resources and resets to a pristine, empty state. I suspect strbuf_detach() probably should make the same claim.

Like this?