filter: add docs for `git_filter_stream_fn`
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
diff --git a/include/git2/sys/filter.h b/include/git2/sys/filter.h
index e43fde5..098f8f7 100644
--- a/include/git2/sys/filter.h
+++ b/include/git2/sys/filter.h
@@ -167,16 +167,16 @@ typedef void GIT_CALLBACK(git_filter_shutdown_fn)(git_filter *self);
*
* The `payload` will be a pointer to a reference payload for the filter.
* This will start as NULL, but `check` can assign to this pointer for
- * later use by the `apply` callback. Note that the value should be heap
- * allocated (not stack), so that it doesn't go away before the `apply`
+ * later use by the `stream` callback. Note that the value should be heap
+ * allocated (not stack), so that it doesn't go away before the `stream`
* callback can use it. If a filter allocates and assigns a value to the
* `payload`, it will need a `cleanup` callback to free the payload.
*/
typedef int GIT_CALLBACK(git_filter_check_fn)(
- git_filter *self,
- void **payload, /* points to NULL ptr on entry, may be set */
+ git_filter *self,
+ void **payload, /* NULL on entry, may be set */
const git_filter_source *src,
- const char **attr_values);
+ const char **attr_values);
/**
* Callback to actually perform the data filtering
@@ -191,30 +191,40 @@ typedef int GIT_CALLBACK(git_filter_check_fn)(
* `check` callback. It may be read from or written to as needed.
*/
typedef int GIT_CALLBACK(git_filter_apply_fn)(
- git_filter *self,
- void **payload, /* may be read and/or set */
- git_buf *to,
- const git_buf *from,
+ git_filter *self,
+ void **payload, /* may be read and/or set */
+ git_buf *to,
+ const git_buf *from,
const git_filter_source *src);
+/**
+ * Callback to perform the data filtering.
+ *
+ * Specified as `filter.stream`, this is a callback that filters data
+ * in a streaming manner. This function will provide a
+ * `git_writestream` that will the original data will be written to;
+ * with that data, the `git_writestream` will then perform the filter
+ * translation and stream the filtered data out to the `next` location.
+ */
typedef int GIT_CALLBACK(git_filter_stream_fn)(
- git_writestream **out,
- git_filter *self,
- void **payload,
+ git_writestream **out,
+ git_filter *self,
+ void **payload,
const git_filter_source *src,
- git_writestream *next);
+ git_writestream *next);
/**
* Callback to clean up after filtering has been applied
*
* Specified as `filter.cleanup`, this is an optional callback invoked
- * after the filter has been applied. If the `check` or `apply` callbacks
- * allocated a `payload` to keep per-source filter state, use this
- * callback to free that payload and release resources as required.
+ * after the filter has been applied. If the `check`, `apply`, or
+ * `stream` callbacks allocated a `payload` to keep per-source filter
+ * state, use this callback to free that payload and release resources
+ * as required.
*/
typedef void GIT_CALLBACK(git_filter_cleanup_fn)(
- git_filter *self,
- void *payload);
+ git_filter *self,
+ void *payload);
/**
* Filter structure used to register custom filters.
@@ -248,21 +258,24 @@ struct git_filter {
/**
* Called to determine whether the filter should be invoked for a
* given file. If this function returns `GIT_PASSTHROUGH` then the
- * `apply` function will not be invoked and the contents will be passed
- * through unmodified.
+ * `stream` or `apply` functions will not be invoked and the
+ * contents will be passed through unmodified.
*/
git_filter_check_fn check;
/**
- * Called to actually apply the filter to file contents. If this
- * function returns `GIT_PASSTHROUGH` then the contents will be passed
- * through unmodified.
+ * Provided for backward compatibility; this will apply the
+ * filter to the given contents in a `git_buf`. Callers should
+ * provide a `stream` function instead.
*/
git_filter_apply_fn apply;
/**
- * Called to apply the filter in a streaming manner. If this is not
- * specified then the system will call `apply` with the whole buffer.
+ * Called to apply the filter, this function will provide a
+ * `git_writestream` that will the original data will be
+ * written to; with that data, the `git_writestream` will then
+ * perform the filter translation and stream the filtered data
+ * out to the `next` location.
*/
git_filter_stream_fn stream;
@@ -289,9 +302,9 @@ GIT_EXTERN(int) git_filter_init(git_filter *filter, unsigned int version);
* As mentioned elsewhere, the initialize callback will not be invoked
* immediately. It is deferred until the filter is used in some way.
*
- * A filter's attribute checks and `check` and `apply` callbacks will be
- * issued in order of `priority` on smudge (to workdir), and in reverse
- * order of `priority` on clean (to odb).
+ * A filter's attribute checks and `check` and `stream` (or `apply`)
+ * callbacks will be issued in order of `priority` on smudge (to
+ * workdir), and in reverse order of `priority` on clean (to odb).
*
* Two filters are preregistered with libgit2:
* - GIT_FILTER_CRLF with priority 0