Merge pull request libgit2#6907 from libgit2/ethomson/blame_cmd

Introduce a blame command

Author: ethomson

examples/blame.c

@@ -97,7 +97,7 @@ int lg2_blame(git_repository *repo, int argc, char *argv[])
 	while (i < rawsize) {
 		const char *eol = memchr(rawdata + i, '\n', (size_t)(rawsize - i));
 		char oid[10] = {0};
-		const git_blame_hunk *hunk = git_blame_get_hunk_byline(blame, line);
+		const git_blame_hunk *hunk = git_blame_hunk_byline(blame, line);
 
 		if (break_on_null_hunk && !hunk)
 			break;

include/git2/blame.h

@@ -87,7 +87,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
@@ -165,6 +165,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,23 +197,94 @@ 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)
 	 */
 	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);
 
 /**
@@ -216,9 +294,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.
@@ -227,50 +305,69 @@ 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
  * @return 0 on success, or an error code. (use git_error_last for information
  *         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.

src/cli/cmd.h

@@ -25,6 +25,7 @@ extern const cli_cmd_spec cli_cmds[];
 extern const cli_cmd_spec *cli_cmd_spec_byname(const char *name);
 
 /* Commands */
+extern int cmd_blame(int argc, char **argv);
 extern int cmd_cat_file(int argc, char **argv);
 extern int cmd_clone(int argc, char **argv);
 extern int cmd_config(int argc, char **argv);