| /* |
| * Copyright (C) the libgit2 contributors. All rights reserved. |
| * |
| * This file is part of libgit2, distributed under the GNU GPL v2 with |
| * a Linking Exception. For full terms see the included COPYING file. |
| */ |
| |
| #ifndef INCLUDE_git_blame_h__ |
| #define INCLUDE_git_blame_h__ |
| |
| #include "common.h" |
| #include "oid.h" |
| |
| /** |
| * @file git2/blame.h |
| * @brief Git blame routines |
| * @defgroup git_blame Git blame routines |
| * @ingroup Git |
| * @{ |
| */ |
| GIT_BEGIN_DECL |
| |
| /** |
| * Flags for indicating option behavior for git_blame APIs. |
| */ |
| typedef enum { |
| /** Normal blame, the default */ |
| GIT_BLAME_NORMAL = 0, |
| /** Track lines that have moved within a file (like `git blame -M`). |
| * NOT IMPLEMENTED. */ |
| 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. */ |
| 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. */ |
| 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. */ |
| GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES = (1<<3), |
| /** Restrict the search of commits to those reachable following only the |
| * first parents. */ |
| GIT_BLAME_FIRST_PARENT = (1<<4), |
| } git_blame_flag_t; |
| |
| /** |
| * Blame options structure |
| * |
| * Use zeros to indicate default settings. It's easiest to use the |
| * `GIT_BLAME_OPTIONS_INIT` macro: |
| * git_blame_options opts = GIT_BLAME_OPTIONS_INIT; |
| * |
| * - `flags` is a combination of the `git_blame_flag_t` values above. |
| * - `min_match_characters` is 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. |
| * - `newest_commit` is the id of the newest commit to consider. The default |
| * is HEAD. |
| * - `oldest_commit` is the id of the oldest commit to consider. The default |
| * is the first commit encountered with a NULL parent. |
| * - `min_line` is the first line in the file to blame. The default is 1 (line |
| * numbers start with 1). |
| * - `max_line` is the last line in the file to blame. The default is the last |
| * line of the file. |
| */ |
| typedef struct git_blame_options { |
| unsigned int version; |
| |
| uint32_t flags; |
| uint16_t min_match_characters; |
| git_oid newest_commit; |
| git_oid oldest_commit; |
| size_t min_line; |
| size_t max_line; |
| } git_blame_options; |
| |
| #define GIT_BLAME_OPTIONS_VERSION 1 |
| #define GIT_BLAME_OPTIONS_INIT {GIT_BLAME_OPTIONS_VERSION} |
| |
| /** |
| * Initializes a `git_blame_options` with default values. Equivalent to |
| * creating an instance with GIT_BLAME_OPTIONS_INIT. |
| * |
| * @param opts The `git_blame_options` struct to initialize |
| * @param version Version of struct; pass `GIT_BLAME_OPTIONS_VERSION` |
| * @return Zero on success; -1 on failure. |
| */ |
| GIT_EXTERN(int) git_blame_init_options( |
| git_blame_options *opts, |
| unsigned int version); |
| |
| /** |
| * 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 |
| * - `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`. |
| * - `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 { |
| size_t lines_in_hunk; |
| |
| git_oid final_commit_id; |
| size_t final_start_line_number; |
| git_signature *final_signature; |
| |
| git_oid orig_commit_id; |
| const char *orig_path; |
| size_t orig_start_line_number; |
| git_signature *orig_signature; |
| |
| char boundary; |
| } git_blame_hunk; |
| |
| |
| /* Opaque structure to hold blame results */ |
| typedef struct git_blame git_blame; |
| |
| /** |
| * Gets the number of hunks that exist in the blame structure. |
| */ |
| GIT_EXTERN(uint32_t) git_blame_get_hunk_count(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_get_hunk_byindex( |
| git_blame *blame, |
| uint32_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_get_hunk_byline( |
| git_blame *blame, |
| size_t lineno); |
| |
| /** |
| * Get the blame for a single file. |
| * |
| * @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 giterr_last for information |
| * about the error.) |
| */ |
| GIT_EXTERN(int) git_blame_file( |
| git_blame **out, |
| git_repository *repo, |
| const char *path, |
| 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. |
| * |
| * 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 |
| * 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 giterr_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); |
| |
| /** |
| * Free memory allocated by git_blame_file or git_blame_buffer. |
| * |
| * @param blame the blame structure to free |
| */ |
| GIT_EXTERN(void) git_blame_free(git_blame *blame); |
| |
| /** @} */ |
| GIT_END_DECL |
| #endif |
| |