Docs for a bunch of git blame stuff

base/libgit2/blame.jl

@@ -1,5 +1,13 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
+"""
+    GitBlame(repo::GitRepo, path::AbstractString; options::BlameOptions=BlameOptions())
+
+Construct a `GitBlame` object for the file at `path`, using change information gleaned
+from the history of `repo`. The `GitBlame` object records who changed which chunks of
+the file when, and how. `options` controls how to separate the contents of the file and
+which commits to probe - see [`BlameOptions`](@ref) for more information.
+"""
 function GitBlame(repo::GitRepo, path::AbstractString; options::BlameOptions=BlameOptions())
     blame_ptr_ptr = Ref{Ptr{Void}}(C_NULL)
     @check ccall((:git_blame_file, :libgit2), Cint,
@@ -8,6 +16,14 @@ function GitBlame(repo::GitRepo, path::AbstractString; options::BlameOptions=Bla
     return GitBlame(repo, blame_ptr_ptr[])
 end
 
+"""
+    counthunks(blame::GitBlame)
+
+Return the number of distinct "hunks" with a file. A hunk may contain multiple lines.
+A hunk is usually a piece of a file that was added/changed/removed together, for example,
+a function added to a source file or an inner loop that was optimized out of
+that function later.
+"""
 function counthunks(blame::GitBlame)
     return ccall((:git_blame_get_hunk_count, :libgit2), Int32, (Ptr{Void},), blame.ptr)
 end

base/libgit2/consts.jl

@@ -27,6 +27,14 @@ module Consts
     const REF_SYMBOLIC = Cint(2)
     const REF_LISTALL  = REF_OID | REF_SYMBOLIC
 
+    # blame
+    const BLAME_NORMAL                          = Cuint(0)
+    const BLAME_TRACK_COPIES_SAME_FILE          = Cuint(1 << 0)
+    const BLAME_TRACK_COPIES_SAME_COMMIT_MOVES  = Cuint(1 << 1)
+    const BLAME_TRACK_COPIES_SAME_COMMIT_COPIES = Cuint(1 << 2)
+    const BLAME_TRACK_COPIES_ANY_COMMIT_COPIES  = Cuint(1 << 3)
+    const BLAME_FIRST_PARENT                    = Cuint(1 << 4)
+
     # checkout
     const CHECKOUT_NONE                    = Cuint(0)
     const CHECKOUT_SAFE                    = Cuint(1 << 0)

base/libgit2/types.jl

@@ -483,6 +483,20 @@ end
     LibGit2.BlameOptions
 
 Matches the [`git_blame_options`](https://libgit2.github.com/libgit2/#HEAD/type/git_blame_options) struct.
+
+The fields represent:
+  * `version`: version of the struct in use, in case this changes later. For now, always `1`.
+  * `flags`: one of `Consts.BLAME_NORMAL` or `Consts.BLAME_FIRST_PARENT` (the other blame flags
+     are not yet implemented by libgit2).
+  * `min_match_characters`: the minimum number of *alphanumeric* characters which much change
+    in a commit in order for the change to be associated with that commit. The default is 20.
+    Only takes effect if one of the `Consts.BLAME_*_COPIES` flags are used, which libgit2 does
+    not implement yet.
+  * `newest_commit`: the [`GitHash`](@ref) of the newest commit from which to look at changes.
+  * `oldest_commit`: the [`GitHash`](@ref) of the oldest commit from which to look at changes.
+  * `min_line`: the first line of the file from which to starting blaming. The default is `1`.
+  * `max_line`: the last line of the file to which to blame. The default is `0`, meaning the
+    last line of the file.
 """
 @kwdef struct BlameOptions
     version::Cuint                    = 1

doc/src/devdocs/libgit2.md

@@ -22,6 +22,7 @@ Base.LibGit2.DiffFile
 Base.LibGit2.DiffOptionsStruct
 Base.LibGit2.FetchHead
 Base.LibGit2.FetchOptions
+Base.LibGit2.GitBlame
 Base.LibGit2.GitBlob
 Base.LibGit2.GitCommit
 Base.LibGit2.GitHash
@@ -38,6 +39,7 @@ Base.LibGit2.GitTag
 Base.LibGit2.GitTree
 Base.LibGit2.IndexEntry
 Base.LibGit2.IndexTime
+Base.LibGit2.BlameOptions
 Base.LibGit2.MergeOptions
 Base.LibGit2.ProxyOptions
 Base.LibGit2.PushOptions
@@ -65,6 +67,7 @@ Base.LibGit2.clone
 Base.LibGit2.commit
 Base.LibGit2.committer
 Base.LibGit2.count(::Function, ::Base.LibGit2.GitRevWalker; ::Base.LibGit2.GitHash, ::Cint, ::Bool)
+Base.LibGit2.counthunks
 Base.LibGit2.create_branch
 Base.LibGit2.credentials_callback
 Base.LibGit2.credentials_cb