libgit2 1.2.0

Author: jeroen

include/git2/apply.h

@@ -100,6 +100,7 @@ GIT_EXTERN(int) git_apply_options_init(git_apply_options *opts, unsigned int ver
  * @param preimage the tree to apply the diff to
  * @param diff the diff to apply
  * @param options the options for the apply (or null for defaults)
+ * @return 0 or an error code
  */
 GIT_EXTERN(int) git_apply_to_tree(
 	git_index **out,
@@ -137,6 +138,7 @@ typedef enum {
  * @param diff the diff to apply
  * @param location the location to apply (workdir, index or both)
  * @param options the options for the apply (or null for defaults)
+ * @return 0 or an error code
  */
 GIT_EXTERN(int) git_apply(
 	git_repository *repo,

include/git2/attr.h

@@ -130,9 +130,32 @@ GIT_EXTERN(git_attr_value_t) git_attr_value(const char *attr);
  *
  * Passing the `GIT_ATTR_CHECK_INCLUDE_HEAD` flag will use attributes
  * from a `.gitattributes` file in the repository at the HEAD revision.
+ *
+ * Passing the `GIT_ATTR_CHECK_INCLUDE_COMMIT` flag will use attributes
+ * from a `.gitattributes` file in a specific commit.
  */
 #define GIT_ATTR_CHECK_NO_SYSTEM        (1 << 2)
 #define GIT_ATTR_CHECK_INCLUDE_HEAD     (1 << 3)
+#define GIT_ATTR_CHECK_INCLUDE_COMMIT   (1 << 4)
+
+/**
+* An options structure for querying attributes.
+*/
+typedef struct {
+	unsigned int version;
+
+	/** A combination of GIT_ATTR_CHECK flags */
+	unsigned int flags;
+
+	/**
+	 * The commit to load attributes from, when
+	 * `GIT_ATTR_CHECK_INCLUDE_COMMIT` is specified.
+	 */
+	git_oid *commit_id;
+} git_attr_options;
+
+#define GIT_ATTR_OPTIONS_VERSION 1
+#define GIT_ATTR_OPTIONS_INIT {GIT_ATTR_OPTIONS_VERSION}
 
 /**
  * Look up the value of one git attribute for path.
@@ -156,6 +179,28 @@ GIT_EXTERN(int) git_attr_get(
 	const char *path,
 	const char *name);
 
+/**
+ * Look up the value of one git attribute for path with extended options.
+ *
+ * @param value_out Output of the value of the attribute.  Use the GIT_ATTR_...
+ *             macros to test for TRUE, FALSE, UNSPECIFIED, etc. or just
+ *             use the string value for attributes set to a value.  You
+ *             should NOT modify or free this value.
+ * @param repo The repository containing the path.
+ * @param opts The `git_attr_options` to use when querying these attributes.
+ * @param path The path to check for attributes.  Relative paths are
+ *             interpreted relative to the repo root.  The file does
+ *             not have to exist, but if it does not, then it will be
+ *             treated as a plain file (not a directory).
+ * @param name The name of the attribute to look up.
+ */
+GIT_EXTERN(int) git_attr_get_ext(
+	const char **value_out,
+	git_repository *repo,
+	git_attr_options *opts,
+	const char *path,
+	const char *name);
+
 /**
  * Look up a list of git attributes for path.
  *
@@ -193,6 +238,30 @@ GIT_EXTERN(int) git_attr_get_many(
 	size_t num_attr,
 	const char **names);
 
+/**
+ * Look up a list of git attributes for path with extended options.
+ *
+ * @param values_out An array of num_attr entries that will have string
+ *             pointers written into it for the values of the attributes.
+ *             You should not modify or free the values that are written
+ *             into this array (although of course, you should free the
+ *             array itself if you allocated it).
+ * @param repo The repository containing the path.
+ * @param opts The `git_attr_options` to use when querying these attributes.
+ * @param path The path inside the repo to check attributes.  This
+ *             does not have to exist, but if it does not, then
+ *             it will be treated as a plain file (i.e. not a directory).
+ * @param num_attr The number of attributes being looked up
+ * @param names An array of num_attr strings containing attribute names.
+ */
+GIT_EXTERN(int) git_attr_get_many_ext(
+	const char **values_out,
+	git_repository *repo,
+	git_attr_options *opts,
+	const char *path,
+	size_t num_attr,
+	const char **names);
+
 /**
  * The callback used with git_attr_foreach.
  *
@@ -231,6 +300,26 @@ GIT_EXTERN(int) git_attr_foreach(
 	git_attr_foreach_cb callback,
 	void *payload);
 
+/**
+ * Loop over all the git attributes for a path with extended options.
+ *
+ * @param repo The repository containing the path.
+ * @param opts The `git_attr_options` to use when querying these attributes.
+ * @param path Path inside the repo to check attributes.  This does not have
+ *             to exist, but if it does not, then it will be treated as a
+ *             plain file (i.e. not a directory).
+ * @param callback Function to invoke on each attribute name and value.
+ *                 See git_attr_foreach_cb.
+ * @param payload Passed on as extra parameter to callback function.
+ * @return 0 on success, non-zero callback return value, or error code
+ */
+GIT_EXTERN(int) git_attr_foreach_ext(
+	git_repository *repo,
+	git_attr_options *opts,
+	const char *path,
+	git_attr_foreach_cb callback,
+	void *payload);
+
 /**
  * Flush the gitattributes cache.
  *

include/git2/blame.h

@@ -26,27 +26,52 @@ GIT_BEGIN_DECL
 typedef enum {
 	/** Normal blame, the default */
 	GIT_BLAME_NORMAL = 0,
-	/** Track lines that have moved within a file (like `git blame -M`).
-	 * NOT IMPLEMENTED. */
+
+	/**
+	 * Track lines that have moved within a file (like `git blame -M`).
+	 *
+	 * This is not yet implemented and reserved for future use.
+	 */
 	GIT_BLAME_TRACK_COPIES_SAME_FILE = (1<<0),
-	/** Track lines that have moved across files in the same commit (like `git blame -C`).
-	 * NOT IMPLEMENTED. */
+
+	/**
+	 * Track lines that have moved across files in the same commit
+	 * (like `git blame -C`).
+	 *
+	 * This is not yet implemented and reserved for future use.
+	 */
 	GIT_BLAME_TRACK_COPIES_SAME_COMMIT_MOVES = (1<<1),
-	/** Track lines that have been copied from another file that exists in the
-	 * same commit (like `git blame -CC`). Implies SAME_FILE.
-	 * NOT IMPLEMENTED. */
+
+	/**
+	 * Track lines that have been copied from another file that exists
+	 * in the same commit (like `git blame -CC`).  Implies SAME_FILE.
+	 *
+	 * This is not yet implemented and reserved for future use.
+	 */
 	GIT_BLAME_TRACK_COPIES_SAME_COMMIT_COPIES = (1<<2),
-	/** Track lines that have been copied from another file that exists in *any*
-	 * commit (like `git blame -CCC`). Implies SAME_COMMIT_COPIES.
-	 * NOT IMPLEMENTED. */
+
+	/**
+	 * Track lines that have been copied from another file that exists in
+	 * *any* commit (like `git blame -CCC`).  Implies SAME_COMMIT_COPIES.
+	 *
+	 * This is not yet implemented and reserved for future use.
+	 */
 	GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES = (1<<3),
-	/** Restrict the search of commits to those reachable following only the
-	 * first parents. */
+
+	/**
+	 * Restrict the search of commits to those reachable following only
+	 * the first parents.
+	 */
 	GIT_BLAME_FIRST_PARENT = (1<<4),
-	/** Use mailmap file to map author and committer names and email addresses
-	 * to canonical real names and email addresses. The mailmap will be read
-	 * from the working directory, or HEAD in a bare repository. */
+
+	/**
+	 * Use mailmap file to map author and committer names and email
+	 * addresses to canonical real names and email addresses. The
+	 * mailmap will be read from the working directory, or HEAD in a
+	 * bare repository.
+	 */
 	GIT_BLAME_USE_MAILMAP = (1<<5),
+
 	/** Ignore whitespace differences */
 	GIT_BLAME_IGNORE_WHITESPACE = (1<<6),
 } git_blame_flag_t;
@@ -63,25 +88,33 @@ typedef struct git_blame_options {
 
 	/** A combination of `git_blame_flag_t` */
 	uint32_t flags;
-	/** The lower bound on the number of alphanumeric
-	 *   characters that must be detected as moving/copying within a file for it to
-	 *   associate those lines with the parent commit. The default value is 20.
-	 *   This value only takes effect if any of the `GIT_BLAME_TRACK_COPIES_*`
-	 *   flags are specified.
+
+	/**
+	 * The lower bound on the number of alphanumeric characters that
+	 * must be detected as moving/copying within a file for it to
+	 * associate those lines with the parent commit. The default value
+	 * is 20.
+	 *
+	 * This value only takes effect if any of the `GIT_BLAME_TRACK_COPIES_*`
+	 * flags are specified.
 	 */
 	uint16_t min_match_characters;
+
 	/** The id of the newest commit to consider. The default is HEAD. */
 	git_oid newest_commit;
+
 	/**
 	 * The id of the oldest commit to consider.
 	 * The default is the first commit encountered with a NULL parent.
 	 */
 	git_oid oldest_commit;
+
 	/**
 	 * The first line in the file to blame.
 	 * The default is 1 (line numbers start with 1).
 	 */
 	size_t min_line;
+
 	/**
 	 * The last line in the file to blame.
 	 * The default is the last line of the file.
@@ -108,41 +141,59 @@ GIT_EXTERN(int) git_blame_options_init(
 
 /**
  * Structure that represents a blame hunk.
- *
- * - `lines_in_hunk` is the number of lines in this hunk
- * - `final_commit_id` is the OID of the commit where this line was last
- *   changed.
- * - `final_start_line_number` is the 1-based line number where this hunk
- *   begins, in the final version of the file
- * - `final_signature` is the author of `final_commit_id`. If
- *   `GIT_BLAME_USE_MAILMAP` has been specified, it will contain the canonical
- *    real name and email address.
- * - `orig_commit_id` is the OID of the commit where this hunk was found.  This
- *   will usually be the same as `final_commit_id`, except when
- *   `GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES` has been specified.
- * - `orig_path` is the path to the file where this hunk originated, as of the
- *   commit specified by `orig_commit_id`.
- * - `orig_start_line_number` is the 1-based line number where this hunk begins
- *   in the file named by `orig_path` in the commit specified by
- *   `orig_commit_id`.
- * - `orig_signature` is the author of `orig_commit_id`. If
- *   `GIT_BLAME_USE_MAILMAP` has been specified, it will contain the canonical
- *    real name and email address.
- * - `boundary` is 1 iff the hunk has been tracked to a boundary commit (the
- *   root, or the commit specified in git_blame_options.oldest_commit)
  */
 typedef struct git_blame_hunk {
+	/**
+	 * The number of lines in this hunk.
+	 */
 	size_t lines_in_hunk;
 
+	/**
+	 * The OID of the commit where this line was last changed.
+	 */
 	git_oid final_commit_id;
+
+	/**
+	 * The 1-based line number where this hunk begins, in the final version
+	 * of the file.
+	 */
 	size_t final_start_line_number;
+
+	/**
+	 * The author of `final_commit_id`. If `GIT_BLAME_USE_MAILMAP` has been
+	 * specified, it will contain the canonical real name and email address.
+	 */
 	git_signature *final_signature;
 
+	/**
+	 * The OID of the commit where this hunk was found.
+	 * This will usually be the same as `final_commit_id`, except when
+	 * `GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES` has been specified.
+	 */
 	git_oid orig_commit_id;
+
+	/**
+	 * The path to the file where this hunk originated, as of the commit
+	 * specified by `orig_commit_id`.
+	 */
 	const char *orig_path;
+
+	/**
+	 * The 1-based line number where this hunk begins in the file named by
+	 * `orig_path` in the commit specified by `orig_commit_id`.
+	 */
 	size_t orig_start_line_number;
+
+	/**
+	 * The author of `orig_commit_id`. If `GIT_BLAME_USE_MAILMAP` has been
+	 * specified, it will contain the canonical real name and email address.
+	 */
 	git_signature *orig_signature;
 
+	/**
+	 * The 1 iff the hunk has been tracked to a boundary commit (the root,
+	 * or the commit specified in git_blame_options.oldest_commit)
+	 */
 	char boundary;
 } git_blame_hunk;
 

include/git2/blob.h

@@ -84,7 +84,7 @@ GIT_EXTERN(git_repository *) git_blob_owner(const git_blob *blob);
  * time.
  *
  * @param blob pointer to the blob
- * @return the pointer
+ * @return the pointer, or NULL on error
  */
 GIT_EXTERN(const void *) git_blob_rawcontent(const git_blob *blob);
 
@@ -113,22 +113,50 @@ typedef enum {
 	 * When set, filters will be loaded from a `.gitattributes` file
 	 * in the HEAD commit.
 	 */
-	GIT_BLOB_FILTER_ATTTRIBUTES_FROM_HEAD = (1 << 2),
+	GIT_BLOB_FILTER_ATTRIBUTES_FROM_HEAD = (1 << 2),
+
+	/**
+	 * When set, filters will be loaded from a `.gitattributes` file
+	 * in the specified commit.
+	 */
+	GIT_BLOB_FILTER_ATTRIBUTES_FROM_COMMIT = (1 << 3),
 } git_blob_filter_flag_t;
 
 /**
  * The options used when applying filter options to a file.
+ *
+ * Initialize with `GIT_BLOB_FILTER_OPTIONS_INIT`. Alternatively, you can
+ * use `git_blob_filter_options_init`.
+ *
  */
 typedef struct {
 	int version;
 
 	/** Flags to control the filtering process, see `git_blob_filter_flag_t` above */
 	uint32_t flags;
+
+	/**
+	 * The commit to load attributes from, when
+	 * `GIT_BLOB_FILTER_ATTRIBUTES_FROM_COMMIT` is specified.
+	 */
+	git_oid *commit_id;
 } git_blob_filter_options;
 
 #define GIT_BLOB_FILTER_OPTIONS_VERSION 1
 #define GIT_BLOB_FILTER_OPTIONS_INIT {GIT_BLOB_FILTER_OPTIONS_VERSION, GIT_BLOB_FILTER_CHECK_FOR_BINARY}
 
+/**
+ * Initialize git_blob_filter_options structure
+ *
+ * Initializes a `git_blob_filter_options` with default values. Equivalent
+ * to creating an instance with `GIT_BLOB_FILTER_OPTIONS_INIT`.
+ *
+ * @param opts The `git_blob_filter_options` struct to initialize.
+ * @param version The struct version; pass `GIT_BLOB_FILTER_OPTIONS_VERSION`.
+ * @return Zero on success; -1 on failure.
+ */
+GIT_EXTERN(int) git_blob_filter_options_init(git_blob_filter_options *opts, unsigned int version);
+
 /**
  * Get a buffer with the filtered content of a blob.
  *
@@ -229,7 +257,7 @@ GIT_EXTERN(int) git_blob_create_from_stream_commit(
  * Write an in-memory buffer to the ODB as a blob
  *
  * @param id return the id of the written blob
- * @param repo repository where to blob will be written
+ * @param repo repository where the blob will be written
  * @param buffer data to be written into the blob
  * @param len length of the data
  * @return 0 or an error code