include/git2/blame.h

   1 /*
   2  * Copyright (C) the libgit2 contributors. All rights reserved.
   3  *
   4  * This file is part of libgit2, distributed under the GNU GPL v2 with
   5  * a Linking Exception. For full terms see the included COPYING file.
   6  */
   7
   8 #ifndef INCLUDE_git_blame_h__
   9 #define INCLUDE_git_blame_h__
  10
  11 #include "common.h"
  12 #include "oid.h"
  13
  14 /**
  15  * @file git2/blame.h
  16  * @brief Git blame routines
  17  * @defgroup git_blame Git blame routines
  18  * @ingroup Git
  19  * @{
  20  */
  21 GIT_BEGIN_DECL
  22
  23 /**
  24  * Flags for indicating option behavior for git_blame APIs.
  25  */
  26 typedef enum {
  27         /** Normal blame, the default */
  28         GIT_BLAME_NORMAL = 0,
  29         /** Track lines that have moved within a file (like `git blame -M`).
  30          * NOT IMPLEMENTED. */
  31         GIT_BLAME_TRACK_COPIES_SAME_FILE = (1<<0),
  32         /** Track lines that have moved across files in the same commit (like `git blame -C`).
  33          * NOT IMPLEMENTED. */
  34         GIT_BLAME_TRACK_COPIES_SAME_COMMIT_MOVES = (1<<1),
  35         /** Track lines that have been copied from another file that exists in the
  36          * same commit (like `git blame -CC`). Implies SAME_FILE.
  37          * NOT IMPLEMENTED. */
  38         GIT_BLAME_TRACK_COPIES_SAME_COMMIT_COPIES = (1<<2),
  39         /** Track lines that have been copied from another file that exists in *any*
  40          * commit (like `git blame -CCC`). Implies SAME_COMMIT_COPIES.
  41          * NOT IMPLEMENTED. */
  42         GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES = (1<<3),
  43         /** Restrict the search of commits to those reachable following only the
  44          * first parents. */
  45         GIT_BLAME_FIRST_PARENT = (1<<4),
  46         /** Use mailmap file to map author and committer names and email addresses
  47          * to canonical real names and email addresses. The mailmap will be read
  48          * from the working directory, or HEAD in a bare repository. */
  49         GIT_BLAME_USE_MAILMAP = (1<<5),
  50 } git_blame_flag_t;
  51
  52 /**
  53  * Blame options structure
  54  *
  55  * Initialize with `GIT_BLAME_OPTIONS_INIT`. Alternatively, you can
  56  * use `git_blame_init_options`.
  57  *
  58  */
  59 typedef struct git_blame_options {
  60         unsigned int version;
  61
  62         /** A combination of `git_blame_flag_t` */
  63         uint32_t flags;
  64         /** The lower bound on the number of alphanumeric
  65          *   characters that must be detected as moving/copying within a file for it to
  66          *   associate those lines with the parent commit. The default value is 20.
  67          *   This value only takes effect if any of the `GIT_BLAME_TRACK_COPIES_*`
  68          *   flags are specified.
  69          */
  70         uint16_t min_match_characters;
  71         /** The id of the newest commit to consider. The default is HEAD. */
  72         git_oid newest_commit;
  73         /**
  74          * The id of the oldest commit to consider.
  75          * The default is the first commit encountered with a NULL parent.
  76          */
  77         git_oid oldest_commit;
  78         /**
  79          * The first line in the file to blame.
  80          * The default is 1 (line numbers start with 1).
  81          */
  82         size_t min_line;
  83         /**
  84          * The last line in the file to blame.
  85          * The default is the last line of the file.
  86          */
  87         size_t max_line;
  88 } git_blame_options;
  89
  90 #define GIT_BLAME_OPTIONS_VERSION 1
  91 #define GIT_BLAME_OPTIONS_INIT {GIT_BLAME_OPTIONS_VERSION}
  92
  93 /**
  94  * Initialize git_blame_options structure
  95  *
  96  * Initializes a `git_blame_options` with default values. Equivalent to creating
  97  * an instance with GIT_BLAME_OPTIONS_INIT.
  98  *
  99  * @param opts The `git_blame_options` struct to initialize.
 100  * @param version The struct version; pass `GIT_BLAME_OPTIONS_VERSION`.
 101  * @return Zero on success; -1 on failure.
 102  */
 103 GIT_EXTERN(int) git_blame_init_options(
 104         git_blame_options *opts,
 105         unsigned int version);
 106
 107 /**
 108  * Structure that represents a blame hunk.
 109  *
 110  * - `lines_in_hunk` is the number of lines in this hunk
 111  * - `final_commit_id` is the OID of the commit where this line was last
 112  *   changed.
 113  * - `final_start_line_number` is the 1-based line number where this hunk
 114  *   begins, in the final version of the file
 115  * - `final_signature` is the author of `final_commit_id`. If
 116  *   `GIT_BLAME_USE_MAILMAP` has been specified, it will contain the canonical
 117  *    real name and email address.
 118  * - `orig_commit_id` is the OID of the commit where this hunk was found.  This
 119  *   will usually be the same as `final_commit_id`, except when
 120  *   `GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES` has been specified.
 121  * - `orig_path` is the path to the file where this hunk originated, as of the
 122  *   commit specified by `orig_commit_id`.
 123  * - `orig_start_line_number` is the 1-based line number where this hunk begins
 124  *   in the file named by `orig_path` in the commit specified by
 125  *   `orig_commit_id`.
 126  * - `orig_signature` is the author of `orig_commit_id`. If
 127  *   `GIT_BLAME_USE_MAILMAP` has been specified, it will contain the canonical
 128  *    real name and email address.
 129  * - `boundary` is 1 iff the hunk has been tracked to a boundary commit (the
 130  *   root, or the commit specified in git_blame_options.oldest_commit)
 131  */
 132 typedef struct git_blame_hunk {
 133         size_t lines_in_hunk;
 134
 135         git_oid final_commit_id;
 136         size_t final_start_line_number;
 137         git_signature *final_signature;
 138
 139         git_oid orig_commit_id;
 140         const char *orig_path;
 141         size_t orig_start_line_number;
 142         git_signature *orig_signature;
 143
 144         char boundary;
 145 } git_blame_hunk;
 146
 147
 148 /** Opaque structure to hold blame results */
 149 typedef struct git_blame git_blame;
 150
 151 /**
 152  * Gets the number of hunks that exist in the blame structure.
 153  */
 154 GIT_EXTERN(uint32_t) git_blame_get_hunk_count(git_blame *blame);
 155
 156 /**
 157  * Gets the blame hunk at the given index.
 158  *
 159  * @param blame the blame structure to query
 160  * @param index index of the hunk to retrieve
 161  * @return the hunk at the given index, or NULL on error
 162  */
 163 GIT_EXTERN(const git_blame_hunk*) git_blame_get_hunk_byindex(
 164                 git_blame *blame,
 165                 uint32_t index);
 166
 167 /**
 168  * Gets the hunk that relates to the given line number in the newest commit.
 169  *
 170  * @param blame the blame structure to query
 171  * @param lineno the (1-based) line number to find a hunk for
 172  * @return the hunk that contains the given line, or NULL on error
 173  */
 174 GIT_EXTERN(const git_blame_hunk*) git_blame_get_hunk_byline(
 175                 git_blame *blame,
 176                 size_t lineno);
 177
 178 /**
 179  * Get the blame for a single file.
 180  *
 181  * @param out pointer that will receive the blame object
 182  * @param repo repository whose history is to be walked
 183  * @param path path to file to consider
 184  * @param options options for the blame operation.  If NULL, this is treated as
 185  *                though GIT_BLAME_OPTIONS_INIT were passed.
 186  * @return 0 on success, or an error code. (use git_error_last for information
 187  *         about the error.)
 188  */
 189 GIT_EXTERN(int) git_blame_file(
 190                 git_blame **out,
 191                 git_repository *repo,
 192                 const char *path,
 193                 git_blame_options *options);
 194
 195
 196 /**
 197  * Get blame data for a file that has been modified in memory. The `reference`
 198  * parameter is a pre-calculated blame for the in-odb history of the file. This
 199  * means that once a file blame is completed (which can be expensive), updating
 200  * the buffer blame is very fast.
 201  *
 202  * Lines that differ between the buffer and the committed version are marked as
 203  * having a zero OID for their final_commit_id.
 204  *
 205  * @param out pointer that will receive the resulting blame data
 206  * @param reference cached blame from the history of the file (usually the output
 207  *                  from git_blame_file)
 208  * @param buffer the (possibly) modified contents of the file
 209  * @param buffer_len number of valid bytes in the buffer
 210  * @return 0 on success, or an error code. (use git_error_last for information
 211  *         about the error)
 212  */
 213 GIT_EXTERN(int) git_blame_buffer(
 214                 git_blame **out,
 215                 git_blame *reference,
 216                 const char *buffer,
 217                 size_t buffer_len);
 218
 219 /**
 220  * Free memory allocated by git_blame_file or git_blame_buffer.
 221  *
 222  * @param blame the blame structure to free
 223  */
 224 GIT_EXTERN(void) git_blame_free(git_blame *blame);
 225
 226 /** @} */
 227 GIT_END_DECL
 228 #endif
 229