rugged 1.3.1 → 1.9.0

data/vendor/libgit2/include/git2/blame.h

@@ -13,9 +13,14 @@
 
 /**
  * @file git2/blame.h
- * @brief Git blame routines
+ * @brief Specify a file's most recent changes per-line
  * @defgroup git_blame Git blame routines
  * @ingroup Git
+ *
+ * Producing a "blame" (or "annotated history") decorates individual
+ * lines in a file with the commit that introduced that particular line
+ * of changes. This can be useful to indicate when and why a particular
+ * change was made.
  * @{
  */
 GIT_BEGIN_DECL
@@ -73,7 +78,7 @@ typedef enum {
 	GIT_BLAME_USE_MAILMAP = (1<<5),
 
 	/** Ignore whitespace differences */
-	GIT_BLAME_IGNORE_WHITESPACE = (1<<6),
+	GIT_BLAME_IGNORE_WHITESPACE = (1<<6)
 } git_blame_flag_t;
 
 /**
@@ -87,7 +92,7 @@ typedef struct git_blame_options {
 	unsigned int version;
 
 	/** A combination of `git_blame_flag_t` */
-	uint32_t flags;
+	unsigned int flags;
 
 	/**
 	 * The lower bound on the number of alphanumeric characters that
@@ -122,7 +127,10 @@ typedef struct git_blame_options {
 	size_t max_line;
 } git_blame_options;
 
+/** Current version for the `git_blame_options` structure */
 #define GIT_BLAME_OPTIONS_VERSION 1
+
+/** Static constructor for `git_blame_options` */
 #define GIT_BLAME_OPTIONS_INIT {GIT_BLAME_OPTIONS_VERSION}
 
 /**
@@ -165,6 +173,13 @@ typedef struct git_blame_hunk {
 	 */
 	git_signature *final_signature;
 
+	/**
+	 * The committer 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_committer;
+
 	/**
 	 * The OID of the commit where this hunk was found.
 	 * This will usually be the same as `final_commit_id`, except when
@@ -190,6 +205,18 @@ typedef struct git_blame_hunk {
 	 */
 	git_signature *orig_signature;
 
+	/**
+	 * The committer 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_committer;
+
+	/*
+	 * The summary of the commit.
+	 */
+	const char *summary;
+
 	/**
 	 * The 1 iff the hunk has been tracked to a boundary commit (the root,
 	 * or the commit specified in git_blame_options.oldest_commit)
@@ -197,13 +224,75 @@ typedef struct git_blame_hunk {
 	char boundary;
 } git_blame_hunk;
 
+/**
+ * Structure that represents a line in a blamed file.
+ */
+typedef struct git_blame_line {
+	const char *ptr;
+	size_t len;
+} git_blame_line;
 
 /** Opaque structure to hold blame results */
 typedef struct git_blame git_blame;
 
+/**
+ * Gets the number of lines that exist in the blame structure.
+ *
+ * @param blame The blame structure to query.
+ * @return The number of line.
+ */
+GIT_EXTERN(size_t) git_blame_linecount(git_blame *blame);
+
 /**
  * Gets the number of hunks that exist in the blame structure.
+ *
+ * @param blame The blame structure to query.
+ * @return The number of hunks.
  */
+GIT_EXTERN(size_t) git_blame_hunkcount(git_blame *blame);
+
+/**
+ * Gets the blame hunk at the given index.
+ *
+ * @param blame the blame structure to query
+ * @param index index of the hunk to retrieve
+ * @return the hunk at the given index, or NULL on error
+ */
+GIT_EXTERN(const git_blame_hunk *) git_blame_hunk_byindex(
+	git_blame *blame,
+	size_t index);
+
+/**
+ * Gets the hunk that relates to the given line number in the newest
+ * commit.
+ *
+ * @param blame the blame structure to query
+ * @param lineno the (1-based) line number to find a hunk for
+ * @return the hunk that contains the given line, or NULL on error
+ */
+GIT_EXTERN(const git_blame_hunk *) git_blame_hunk_byline(
+	git_blame *blame,
+	size_t lineno);
+
+/**
+ * Gets the information about the line in the blame.
+ *
+ * @param blame the blame structure to query
+ * @param idx the (1-based) line number
+ * @return the blamed line, or NULL on error
+ */
+GIT_EXTERN(const git_blame_line *) git_blame_line_byindex(
+	git_blame *blame,
+	size_t idx);
+
+#ifndef GIT_DEPRECATE_HARD
+/**
+ * Gets the number of hunks that exist in the blame structure.
+ *
+ * @param blame The blame structure to query.
+ * @return The number of hunks.
+ */
+
 GIT_EXTERN(uint32_t) git_blame_get_hunk_count(git_blame *blame);
 
 /**
@@ -213,9 +302,9 @@ GIT_EXTERN(uint32_t) git_blame_get_hunk_count(git_blame *blame);
  * @param index index of the hunk to retrieve
  * @return the hunk at the given index, or NULL on error
  */
-GIT_EXTERN(const git_blame_hunk*) git_blame_get_hunk_byindex(
-		git_blame *blame,
-		uint32_t index);
+GIT_EXTERN(const git_blame_hunk *) git_blame_get_hunk_byindex(
+	git_blame *blame,
+	uint32_t index);
 
 /**
  * Gets the hunk that relates to the given line number in the newest commit.
@@ -224,39 +313,58 @@ GIT_EXTERN(const git_blame_hunk*) git_blame_get_hunk_byindex(
  * @param lineno the (1-based) line number to find a hunk for
  * @return the hunk that contains the given line, or NULL on error
  */
-GIT_EXTERN(const git_blame_hunk*) git_blame_get_hunk_byline(
-		git_blame *blame,
-		size_t lineno);
+GIT_EXTERN(const git_blame_hunk *) git_blame_get_hunk_byline(
+	git_blame *blame,
+	size_t lineno);
+#endif
 
 /**
- * Get the blame for a single file.
+ * Get the blame for a single file in the repository.
  *
  * @param out pointer that will receive the blame object
  * @param repo repository whose history is to be walked
  * @param path path to file to consider
- * @param options options for the blame operation.  If NULL, this is treated as
- *                though GIT_BLAME_OPTIONS_INIT were passed.
- * @return 0 on success, or an error code. (use git_error_last for information
- *         about the error.)
+ * @param options options for the blame operation or NULL
+ * @return 0 on success, or an error code
  */
 GIT_EXTERN(int) git_blame_file(
-		git_blame **out,
-		git_repository *repo,
-		const char *path,
-		git_blame_options *options);
+	git_blame **out,
+	git_repository *repo,
+	const char *path,
+	git_blame_options *options);
 
+/**
+ * Get the blame for a single file in the repository, using the specified
+ * buffer contents as the uncommitted changes of the file (the working
+ * directory contents).
+ *
+ * @param out pointer that will receive the blame object
+ * @param repo repository whose history is to be walked
+ * @param path path to file to consider
+ * @param contents the uncommitted changes
+ * @param contents_len the length of the changes buffer
+ * @param options options for the blame operation or NULL
+ * @return 0 on success, or an error code
+ */
+GIT_EXTERN(int) git_blame_file_from_buffer(
+	git_blame **out,
+	git_repository *repo,
+	const char *path,
+	const char *contents,
+	size_t contents_len,
+	git_blame_options *options);
 
 /**
- * Get blame data for a file that has been modified in memory. The `reference`
- * parameter is a pre-calculated blame for the in-odb history of the file. This
- * means that once a file blame is completed (which can be expensive), updating
- * the buffer blame is very fast.
+ * Get blame data for a file that has been modified in memory. The `blame`
+ * parameter is a pre-calculated blame for the in-odb history of the file.
+ * This means that once a file blame is completed (which can be expensive),
+ * updating the buffer blame is very fast.
  *
- * Lines that differ between the buffer and the committed version are marked as
- * having a zero OID for their final_commit_id.
+ * Lines that differ between the buffer and the committed version are
+ * marked as having a zero OID for their final_commit_id.
  *
  * @param out pointer that will receive the resulting blame data
- * @param reference cached blame from the history of the file (usually the output
+ * @param base cached blame from the history of the file (usually the output
  *                  from git_blame_file)
  * @param buffer the (possibly) modified contents of the file
  * @param buffer_len number of valid bytes in the buffer
@@ -264,10 +372,10 @@ GIT_EXTERN(int) git_blame_file(
  *         about the error)
  */
 GIT_EXTERN(int) git_blame_buffer(
-		git_blame **out,
-		git_blame *reference,
-		const char *buffer,
-		size_t buffer_len);
+	git_blame **out,
+	git_blame *base,
+	const char *buffer,
+	size_t buffer_len);
 
 /**
  * Free memory allocated by git_blame_file or git_blame_buffer.

data/vendor/libgit2/include/git2/blob.h

@@ -15,9 +15,13 @@
 
 /**
  * @file git2/blob.h
- * @brief Git blob load and write routines
+ * @brief A blob represents a file in a git repository.
  * @defgroup git_blob Git blob load and write routines
  * @ingroup Git
+ *
+ * A blob represents a file in a git repository. This is the raw data
+ * as it is stored in the repository itself. Blobs may be "filtered"
+ * to produce the on-disk content.
  * @{
  */
 GIT_BEGIN_DECL
@@ -25,12 +29,15 @@ GIT_BEGIN_DECL
 /**
  * Lookup a blob object from a repository.
  *
- * @param blob pointer to the looked up blob
+ * @param[out] blob pointer to the looked up blob
  * @param repo the repo to use when locating the blob.
  * @param id identity of the blob to locate.
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_blob_lookup(git_blob **blob, git_repository *repo, const git_oid *id);
+GIT_EXTERN(int) git_blob_lookup(
+	git_blob **blob,
+	git_repository *repo,
+	const git_oid *id);
 
 /**
  * Lookup a blob object from a repository,
@@ -38,7 +45,7 @@ GIT_EXTERN(int) git_blob_lookup(git_blob **blob, git_repository *repo, const git
  *
  * @see git_object_lookup_prefix
  *
- * @param blob pointer to the looked up blob
+ * @param[out] blob pointer to the looked up blob
  * @param repo the repo to use when locating the blob.
  * @param id identity of the blob to locate.
  * @param len the length of the short identifier
@@ -84,7 +91,7 @@ GIT_EXTERN(git_repository *) git_blob_owner(const git_blob *blob);
  * time.
  *
  * @param blob pointer to the blob
- * @return the pointer, or NULL on error
+ * @return @type `unsigned char *` the pointer, or NULL on error
  */
 GIT_EXTERN(const void *) git_blob_rawcontent(const git_blob *blob);
 
@@ -92,12 +99,14 @@ GIT_EXTERN(const void *) git_blob_rawcontent(const git_blob *blob);
  * Get the size in bytes of the contents of a blob
  *
  * @param blob pointer to the blob
- * @return size on bytes
+ * @return size in bytes
  */
 GIT_EXTERN(git_object_size_t) git_blob_rawsize(const git_blob *blob);
 
 /**
  * Flags to control the functionality of `git_blob_filter`.
+ *
+ * @flags
  */
 typedef enum {
 	/** When set, filters will not be applied to binary files. */
@@ -119,7 +128,7 @@ typedef enum {
 	 * 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_ATTRIBUTES_FROM_COMMIT = (1 << 3)
 } git_blob_filter_flag_t;
 
 /**
@@ -128,16 +137,34 @@ typedef enum {
  * Initialize with `GIT_BLOB_FILTER_OPTIONS_INIT`. Alternatively, you can
  * use `git_blob_filter_options_init`.
  *
+ * @options[version] GIT_BLOB_FILTER_OPTIONS_VERSION
+ * @options[init_macro] GIT_BLOB_FILTER_OPTIONS_INIT
+ * @options[init_function] git_blob_filter_options_init
  */
 typedef struct {
+	/** Version number of the options structure. */
 	int version;
 
-	/** Flags to control the filtering process, see `git_blob_filter_flag_t` above */
+	/**
+	 * Flags to control the filtering process, see `git_blob_filter_flag_t` above.
+	 *
+	 * @type[flags] git_blob_filter_flag_t
+	 */
 	uint32_t flags;
 
 #ifdef GIT_DEPRECATE_HARD
+	/**
+	 * Unused and reserved for ABI compatibility.
+	 *
+	 * @deprecated this value should not be set
+	 */
 	void *reserved;
 #else
+	/**
+	 * This value is unused and reserved for API compatibility.
+	 *
+	 * @deprecated this value should not be set
+	 */
 	git_oid *commit_id;
 #endif
 
@@ -148,8 +175,18 @@ typedef struct {
 	git_oid attr_commit_id;
 } git_blob_filter_options;
 
+/**
+ * The current version number for the `git_blob_filter_options` structure ABI.
+ */
 #define GIT_BLOB_FILTER_OPTIONS_VERSION 1
-#define GIT_BLOB_FILTER_OPTIONS_INIT {GIT_BLOB_FILTER_OPTIONS_VERSION, GIT_BLOB_FILTER_CHECK_FOR_BINARY}
+
+/**
+ * The default values for `git_blob_filter_options`.
+ */
+#define GIT_BLOB_FILTER_OPTIONS_INIT { \
+		GIT_BLOB_FILTER_OPTIONS_VERSION, \
+		GIT_BLOB_FILTER_CHECK_FOR_BINARY \
+	}
 
 /**
  * Initialize git_blob_filter_options structure
@@ -158,10 +195,12 @@ typedef struct {
  * 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`.
+ * @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);
+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.
@@ -171,7 +210,7 @@ GIT_EXTERN(int) git_blob_filter_options_init(git_blob_filter_options *opts, unsi
  * CRLF filtering or other types of changes depending on the file
  * attributes set for the blob and the content detected in it.
  *
- * The output is written into a `git_buf` which the caller must free
+ * The output is written into a `git_buf` which the caller must dispose
  * when done (via `git_buf_dispose`).
  *
  * If no filters need to be applied, then the `out` buffer will just
@@ -183,7 +222,7 @@ GIT_EXTERN(int) git_blob_filter_options_init(git_blob_filter_options *opts, unsi
  * @param blob Pointer to the blob
  * @param as_path Path used for file attribute lookups, etc.
  * @param opts Options to use for filtering the blob
- * @return 0 on success or an error code
+ * @return @type[enum] git_error_code 0 on success or an error code
  */
 GIT_EXTERN(int) git_blob_filter(
 	git_buf *out,
@@ -192,10 +231,10 @@ GIT_EXTERN(int) git_blob_filter(
 	git_blob_filter_options *opts);
 
 /**
- * Read a file from the working folder of a repository
- * and write it to the Object Database as a loose blob
+ * Read a file from the working folder of a repository and write it
+ * to the object database.
  *
- * @param id return the id of the written blob
+ * @param[out] id return the id of the written blob
  * @param repo repository where the blob will be written.
  *	this repository cannot be bare
  * @param relative_path file from which the blob will be created,
@@ -205,19 +244,23 @@ GIT_EXTERN(int) git_blob_filter(
 GIT_EXTERN(int) git_blob_create_from_workdir(git_oid *id, git_repository *repo, const char *relative_path);
 
 /**
- * Read a file from the filesystem and write its content
- * to the Object Database as a loose blob
+ * Read a file from the filesystem (not necessarily inside the
+ * working folder of the repository) and write it to the object
+ * database.
  *
- * @param id return the id of the written blob
+ * @param[out] id return the id of the written blob
  * @param repo repository where the blob will be written.
  *	this repository can be bare or not
  * @param path file from which the blob will be created
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_blob_create_from_disk(git_oid *id, git_repository *repo, const char *path);
+GIT_EXTERN(int) git_blob_create_from_disk(
+	git_oid *id,
+	git_repository *repo,
+	const char *path);
 
 /**
- * Create a stream to write a new blob into the object db
+ * Create a stream to write a new blob into the object database.
  *
  * This function may need to buffer the data on disk and will in
  * general not be the right choice if you know the size of the data
@@ -234,7 +277,7 @@ GIT_EXTERN(int) git_blob_create_from_disk(git_oid *id, git_repository *repo, con
  * what git filters should be applied to the object before it is written
  * to the object database.
  *
- * @param out the stream into which to write
+ * @param[out] out the stream into which to write
  * @param repo Repository where the blob will be written.
  *        This repository can be bare or not.
  * @param hintpath If not NULL, will be used to select data filters
@@ -247,11 +290,11 @@ GIT_EXTERN(int) git_blob_create_from_stream(
 	const char *hintpath);
 
 /**
- * Close the stream and write the blob to the object db
+ * Close the stream and finalize writing the blob to the object database.
  *
  * The stream will be closed and freed.
  *
- * @param out the id of the new blob
+ * @param[out] out the id of the new blob
  * @param stream the stream to close
  * @return 0 or an error code
  */
@@ -260,9 +303,9 @@ GIT_EXTERN(int) git_blob_create_from_stream_commit(
 	git_writestream *stream);
 
 /**
- * Write an in-memory buffer to the ODB as a blob
+ * Write an in-memory buffer to the object database as a blob.
  *
- * @param id return the id of the written blob
+ * @param[out] id return the id of the written blob
  * @param repo repository where the blob will be written
  * @param buffer data to be written into the blob
  * @param len length of the data
@@ -272,24 +315,37 @@ GIT_EXTERN(int) git_blob_create_from_buffer(
 	git_oid *id, git_repository *repo, const void *buffer, size_t len);
 
 /**
- * Determine if the blob content is most certainly binary or not.
+ * Determine if the blob content is most likely binary or not.
  *
  * The heuristic used to guess if a file is binary is taken from core git:
  * Searching for NUL bytes and looking for a reasonable ratio of printable
  * to non-printable characters among the first 8000 bytes.
  *
  * @param blob The blob which content should be analyzed
- * @return 1 if the content of the blob is detected
+ * @return @type bool 1 if the content of the blob is detected
  * as binary; 0 otherwise.
  */
 GIT_EXTERN(int) git_blob_is_binary(const git_blob *blob);
 
+/**
+ * Determine if the given content is most certainly binary or not;
+ * this is the same mechanism used by `git_blob_is_binary` but only
+ * looking at raw data.
+ *
+ * @param data The blob data which content should be analyzed
+ * @param len The length of the data
+ * @return 1 if the content of the blob is detected
+ * as binary; 0 otherwise.
+ */
+GIT_EXTERN(int) git_blob_data_is_binary(const char *data, size_t len);
+
 /**
  * Create an in-memory copy of a blob. The copy must be explicitly
  * free'd or it will leak.
  *
- * @param out Pointer to store the copy of the object
+ * @param[out] out Pointer to store the copy of the object
  * @param source Original object to copy
+ * @return 0.
  */
 GIT_EXTERN(int) git_blob_dup(git_blob **out, git_blob *source);
 

data/vendor/libgit2/include/git2/branch.h

@@ -13,9 +13,15 @@
 
 /**
  * @file git2/branch.h
- * @brief Git branch parsing routines
+ * @brief Branch creation and handling
  * @defgroup git_branch Git branch management
  * @ingroup Git
+ *
+ * A branch is a specific type of reference, at any particular time,
+ * a git working directory typically is said to have a branch "checked out",
+ * meaning that commits that are created will be made "on" a branch.
+ * This occurs by updating the branch reference to point to the new
+ * commit. The checked out branch is indicated by the `HEAD` meta-ref.
  * @{
  */
 GIT_BEGIN_DECL
@@ -33,16 +39,13 @@ GIT_BEGIN_DECL
  * See `git_tag_create()` for rules about valid names.
  *
  * @param out Pointer where to store the underlying reference.
- *
+ * @param repo the repository to create the branch in.
  * @param branch_name Name for the branch; this name is
- * validated for consistency. It should also not conflict with
- * an already existing branch name.
- *
+ *   validated for consistency. It should also not conflict with
+ *   an already existing branch name.
  * @param target Commit to which this branch should point. This object
- * must belong to the given `repo`.
- *
+ *   must belong to the given `repo`.
  * @param force Overwrite existing branch.
- *
  * @return 0, GIT_EINVALIDSPEC or an error code.
  * A proper reference is written in the refs/heads namespace
  * pointing to the provided target commit.
@@ -61,15 +64,21 @@ GIT_EXTERN(int) git_branch_create(
  * commit, which lets you specify which extended sha syntax string was
  * specified by a user, allowing for more exact reflog messages.
  *
- * See the documentation for `git_branch_create()`.
- *
- * @see git_branch_create
+ * @param ref_out Pointer where to store the underlying reference.
+ * @param repo the repository to create the branch in.
+ * @param branch_name Name for the branch; this name is
+ *   validated for consistency. It should also not conflict with
+ *   an already existing branch name.
+ * @param target Annotated commit to which this branch should point. This
+ *   object must belong to the given `repo`.
+ * @param force Overwrite existing branch.
+ * @return 0, GIT_EINVALIDSPEC or an error code.
  */
 GIT_EXTERN(int) git_branch_create_from_annotated(
 	git_reference **ref_out,
-	git_repository *repository,
+	git_repository *repo,
 	const char *branch_name,
-	const git_annotated_commit *commit,
+	const git_annotated_commit *target,
 	int force);
 
 /**
@@ -127,8 +136,8 @@ GIT_EXTERN(void) git_branch_iterator_free(git_branch_iterator *iter);
  * See `git_tag_create()` for rules about valid names.
  *
  * Note that if the move succeeds, the old reference object will not
- + be valid anymore, and should be freed immediately by the user using
- + `git_reference_free()`.
+ * be valid anymore, and should be freed immediately by the user using
+ * `git_reference_free()`.
  *
  * @param out New reference object for the updated name.
  *
@@ -220,7 +229,7 @@ GIT_EXTERN(int) git_branch_upstream(
  * @param branch the branch to configure
  * @param branch_name remote-tracking or local branch to set as upstream.
  *
- * @return 0 on success; GIT_ENOTFOUND if there's no branch named `branch_name`
+ * @return @type git_error_t 0 on success; GIT_ENOTFOUND if there's no branch named `branch_name`
  *         or an error code
  */
 GIT_EXTERN(int) git_branch_set_upstream(