include/git2/blame.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007
0008 #ifndef INCLUDE_git_blame_h__
0009 #define INCLUDE_git_blame_h__
0010
0011 #include "common.h"
0012 #include "oid.h"
0013
0014 /**
0015  * @file git2/blame.h
0016  * @brief Git blame routines
0017  * @defgroup git_blame Git blame routines
0018  * @ingroup Git
0019  * @{
0020  */
0021 GIT_BEGIN_DECL
0022
0023 /**
0024  * Flags for indicating option behavior for git_blame APIs.
0025  */
0026 typedef enum {
0027     /** Normal blame, the default */
0028     GIT_BLAME_NORMAL = 0,
0029
0030     /**
0031      * Track lines that have moved within a file (like `git blame -M`).
0032      *
0033      * This is not yet implemented and reserved for future use.
0034      */
0035     GIT_BLAME_TRACK_COPIES_SAME_FILE = (1<<0),
0036
0037     /**
0038      * Track lines that have moved across files in the same commit
0039      * (like `git blame -C`).
0040      *
0041      * This is not yet implemented and reserved for future use.
0042      */
0043     GIT_BLAME_TRACK_COPIES_SAME_COMMIT_MOVES = (1<<1),
0044
0045     /**
0046      * Track lines that have been copied from another file that exists
0047      * in the same commit (like `git blame -CC`).  Implies SAME_FILE.
0048      *
0049      * This is not yet implemented and reserved for future use.
0050      */
0051     GIT_BLAME_TRACK_COPIES_SAME_COMMIT_COPIES = (1<<2),
0052
0053     /**
0054      * Track lines that have been copied from another file that exists in
0055      * *any* commit (like `git blame -CCC`).  Implies SAME_COMMIT_COPIES.
0056      *
0057      * This is not yet implemented and reserved for future use.
0058      */
0059     GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES = (1<<3),
0060
0061     /**
0062      * Restrict the search of commits to those reachable following only
0063      * the first parents.
0064      */
0065     GIT_BLAME_FIRST_PARENT = (1<<4),
0066
0067     /**
0068      * Use mailmap file to map author and committer names and email
0069      * addresses to canonical real names and email addresses. The
0070      * mailmap will be read from the working directory, or HEAD in a
0071      * bare repository.
0072      */
0073     GIT_BLAME_USE_MAILMAP = (1<<5),
0074
0075     /** Ignore whitespace differences */
0076     GIT_BLAME_IGNORE_WHITESPACE = (1<<6)
0077 } git_blame_flag_t;
0078
0079 /**
0080  * Blame options structure
0081  *
0082  * Initialize with `GIT_BLAME_OPTIONS_INIT`. Alternatively, you can
0083  * use `git_blame_options_init`.
0084  *
0085  */
0086 typedef struct git_blame_options {
0087     unsigned int version;
0088
0089     /** A combination of `git_blame_flag_t` */
0090     uint32_t flags;
0091
0092     /**
0093      * The lower bound on the number of alphanumeric characters that
0094      * must be detected as moving/copying within a file for it to
0095      * associate those lines with the parent commit. The default value
0096      * is 20.
0097      *
0098      * This value only takes effect if any of the `GIT_BLAME_TRACK_COPIES_*`
0099      * flags are specified.
0100      */
0101     uint16_t min_match_characters;
0102
0103     /** The id of the newest commit to consider. The default is HEAD. */
0104     git_oid newest_commit;
0105
0106     /**
0107      * The id of the oldest commit to consider.
0108      * The default is the first commit encountered with a NULL parent.
0109      */
0110     git_oid oldest_commit;
0111
0112     /**
0113      * The first line in the file to blame.
0114      * The default is 1 (line numbers start with 1).
0115      */
0116     size_t min_line;
0117
0118     /**
0119      * The last line in the file to blame.
0120      * The default is the last line of the file.
0121      */
0122     size_t max_line;
0123 } git_blame_options;
0124
0125 #define GIT_BLAME_OPTIONS_VERSION 1
0126 #define GIT_BLAME_OPTIONS_INIT {GIT_BLAME_OPTIONS_VERSION}
0127
0128 /**
0129  * Initialize git_blame_options structure
0130  *
0131  * Initializes a `git_blame_options` with default values. Equivalent to creating
0132  * an instance with GIT_BLAME_OPTIONS_INIT.
0133  *
0134  * @param opts The `git_blame_options` struct to initialize.
0135  * @param version The struct version; pass `GIT_BLAME_OPTIONS_VERSION`.
0136  * @return Zero on success; -1 on failure.
0137  */
0138 GIT_EXTERN(int) git_blame_options_init(
0139     git_blame_options *opts,
0140     unsigned int version);
0141
0142 /**
0143  * Structure that represents a blame hunk.
0144  */
0145 typedef struct git_blame_hunk {
0146     /**
0147      * The number of lines in this hunk.
0148      */
0149     size_t lines_in_hunk;
0150
0151     /**
0152      * The OID of the commit where this line was last changed.
0153      */
0154     git_oid final_commit_id;
0155
0156     /**
0157      * The 1-based line number where this hunk begins, in the final version
0158      * of the file.
0159      */
0160     size_t final_start_line_number;
0161
0162     /**
0163      * The author of `final_commit_id`. If `GIT_BLAME_USE_MAILMAP` has been
0164      * specified, it will contain the canonical real name and email address.
0165      */
0166     git_signature *final_signature;
0167
0168     /**
0169      * The OID of the commit where this hunk was found.
0170      * This will usually be the same as `final_commit_id`, except when
0171      * `GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES` has been specified.
0172      */
0173     git_oid orig_commit_id;
0174
0175     /**
0176      * The path to the file where this hunk originated, as of the commit
0177      * specified by `orig_commit_id`.
0178      */
0179     const char *orig_path;
0180
0181     /**
0182      * The 1-based line number where this hunk begins in the file named by
0183      * `orig_path` in the commit specified by `orig_commit_id`.
0184      */
0185     size_t orig_start_line_number;
0186
0187     /**
0188      * The author of `orig_commit_id`. If `GIT_BLAME_USE_MAILMAP` has been
0189      * specified, it will contain the canonical real name and email address.
0190      */
0191     git_signature *orig_signature;
0192
0193     /**
0194      * The 1 iff the hunk has been tracked to a boundary commit (the root,
0195      * or the commit specified in git_blame_options.oldest_commit)
0196      */
0197     char boundary;
0198 } git_blame_hunk;
0199
0200
0201 /** Opaque structure to hold blame results */
0202 typedef struct git_blame git_blame;
0203
0204 /**
0205  * Gets the number of hunks that exist in the blame structure.
0206  *
0207  * @param blame The blame structure to query.
0208  * @return The number of hunks.
0209  */
0210 GIT_EXTERN(uint32_t) git_blame_get_hunk_count(git_blame *blame);
0211
0212 /**
0213  * Gets the blame hunk at the given index.
0214  *
0215  * @param blame the blame structure to query
0216  * @param index index of the hunk to retrieve
0217  * @return the hunk at the given index, or NULL on error
0218  */
0219 GIT_EXTERN(const git_blame_hunk*) git_blame_get_hunk_byindex(
0220         git_blame *blame,
0221         uint32_t index);
0222
0223 /**
0224  * Gets the hunk that relates to the given line number in the newest commit.
0225  *
0226  * @param blame the blame structure to query
0227  * @param lineno the (1-based) line number to find a hunk for
0228  * @return the hunk that contains the given line, or NULL on error
0229  */
0230 GIT_EXTERN(const git_blame_hunk*) git_blame_get_hunk_byline(
0231         git_blame *blame,
0232         size_t lineno);
0233
0234 /**
0235  * Get the blame for a single file.
0236  *
0237  * @param out pointer that will receive the blame object
0238  * @param repo repository whose history is to be walked
0239  * @param path path to file to consider
0240  * @param options options for the blame operation.  If NULL, this is treated as
0241  *                though GIT_BLAME_OPTIONS_INIT were passed.
0242  * @return 0 on success, or an error code. (use git_error_last for information
0243  *         about the error.)
0244  */
0245 GIT_EXTERN(int) git_blame_file(
0246         git_blame **out,
0247         git_repository *repo,
0248         const char *path,
0249         git_blame_options *options);
0250
0251
0252 /**
0253  * Get blame data for a file that has been modified in memory. The `reference`
0254  * parameter is a pre-calculated blame for the in-odb history of the file. This
0255  * means that once a file blame is completed (which can be expensive), updating
0256  * the buffer blame is very fast.
0257  *
0258  * Lines that differ between the buffer and the committed version are marked as
0259  * having a zero OID for their final_commit_id.
0260  *
0261  * @param out pointer that will receive the resulting blame data
0262  * @param reference cached blame from the history of the file (usually the output
0263  *                  from git_blame_file)
0264  * @param buffer the (possibly) modified contents of the file
0265  * @param buffer_len number of valid bytes in the buffer
0266  * @return 0 on success, or an error code. (use git_error_last for information
0267  *         about the error)
0268  */
0269 GIT_EXTERN(int) git_blame_buffer(
0270         git_blame **out,
0271         git_blame *reference,
0272         const char *buffer,
0273         size_t buffer_len);
0274
0275 /**
0276  * Free memory allocated by git_blame_file or git_blame_buffer.
0277  *
0278  * @param blame the blame structure to free
0279  */
0280 GIT_EXTERN(void) git_blame_free(git_blame *blame);
0281
0282 /** @} */
0283 GIT_END_DECL
0284 #endif
0285