Skip to content

Commit 62d8671

Browse files
committed
Docs for a bunch of git blame stuff
1 parent 9b3b2ff commit 62d8671

File tree

4 files changed

+41
-0
lines changed

4 files changed

+41
-0
lines changed

base/libgit2/blame.jl

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,13 @@
11
# This file is a part of Julia. License is MIT: https://julialang.org/license
22

3+
"""
4+
GitBlame(repo::GitRepo, path::AbstractString; options::BlameOptions=BlameOptions())
5+
6+
Construct a `GitBlame` object for the file at `path`, using change information gleaned
7+
from the history of `repo`. The `GitBlame` object records who changed which chunks of
8+
the file when, and how. `options` controls how to separate the contents of the file and
9+
which commits to probe - see [`BlameOptions`](@ref) for more information.
10+
"""
311
function GitBlame(repo::GitRepo, path::AbstractString; options::BlameOptions=BlameOptions())
412
blame_ptr_ptr = Ref{Ptr{Void}}(C_NULL)
513
@check ccall((:git_blame_file, :libgit2), Cint,
@@ -8,6 +16,14 @@ function GitBlame(repo::GitRepo, path::AbstractString; options::BlameOptions=Bla
816
return GitBlame(repo, blame_ptr_ptr[])
917
end
1018

19+
"""
20+
counthunks(blame::GitBlame)
21+
22+
Return the number of distinct "hunks" with a file. A hunk may contain multiple lines.
23+
A hunk is usually a piece of a file that was added/changed/removed together, for example,
24+
a function added to a source file or an inner loop that was optimized out of
25+
that function later.
26+
"""
1127
function counthunks(blame::GitBlame)
1228
return ccall((:git_blame_get_hunk_count, :libgit2), Int32, (Ptr{Void},), blame.ptr)
1329
end

base/libgit2/consts.jl

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,14 @@ module Consts
2727
const REF_SYMBOLIC = Cint(2)
2828
const REF_LISTALL = REF_OID | REF_SYMBOLIC
2929

30+
# blame
31+
const BLAME_NORMAL = Cuint(0)
32+
const BLAME_TRACK_COPIES_SAME_FILE = Cuint(1 << 0)
33+
const BLAME_TRACK_COPIES_SAME_COMMIT_MOVES = Cuint(1 << 1)
34+
const BLAME_TRACK_COPIES_SAME_COMMIT_COPIES = Cuint(1 << 2)
35+
const BLAME_TRACK_COPIES_ANY_COMMIT_COPIES = Cuint(1 << 3)
36+
const BLAME_FIRST_PARENT = Cuint(1 << 4)
37+
3038
# checkout
3139
const CHECKOUT_NONE = Cuint(0)
3240
const CHECKOUT_SAFE = Cuint(1 << 0)

base/libgit2/types.jl

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -483,6 +483,20 @@ end
483483
LibGit2.BlameOptions
484484
485485
Matches the [`git_blame_options`](https://libgit2.github.com/libgit2/#HEAD/type/git_blame_options) struct.
486+
487+
The fields represent:
488+
* `version`: version of the struct in use, in case this changes later. For now, always `1`.
489+
* `flags`: one of `Consts.BLAME_NORMAL` or `Consts.BLAME_FIRST_PARENT` (the other blame flags
490+
are not yet implemented by libgit2).
491+
* `min_match_characters`: the minimum number of *alphanumeric* characters which much change
492+
in a commit in order for the change to be associated with that commit. The default is 20.
493+
Only takes effect if one of the `Consts.BLAME_*_COPIES` flags are used, which libgit2 does
494+
not implement yet.
495+
* `newest_commit`: the [`GitHash`](@ref) of the newest commit from which to look at changes.
496+
* `oldest_commit`: the [`GitHash`](@ref) of the oldest commit from which to look at changes.
497+
* `min_line`: the first line of the file from which to starting blaming. The default is `1`.
498+
* `max_line`: the last line of the file to which to blame. The default is `0`, meaning the
499+
last line of the file.
486500
"""
487501
@kwdef struct BlameOptions
488502
version::Cuint = 1

doc/src/devdocs/libgit2.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ Base.LibGit2.DiffFile
2222
Base.LibGit2.DiffOptionsStruct
2323
Base.LibGit2.FetchHead
2424
Base.LibGit2.FetchOptions
25+
Base.LibGit2.GitBlame
2526
Base.LibGit2.GitBlob
2627
Base.LibGit2.GitCommit
2728
Base.LibGit2.GitHash
@@ -38,6 +39,7 @@ Base.LibGit2.GitTag
3839
Base.LibGit2.GitTree
3940
Base.LibGit2.IndexEntry
4041
Base.LibGit2.IndexTime
42+
Base.LibGit2.BlameOptions
4143
Base.LibGit2.MergeOptions
4244
Base.LibGit2.ProxyOptions
4345
Base.LibGit2.PushOptions
@@ -65,6 +67,7 @@ Base.LibGit2.clone
6567
Base.LibGit2.commit
6668
Base.LibGit2.committer
6769
Base.LibGit2.count(::Function, ::Base.LibGit2.GitRevWalker; ::Base.LibGit2.GitHash, ::Cint, ::Bool)
70+
Base.LibGit2.counthunks
6871
Base.LibGit2.create_branch
6972
Base.LibGit2.credentials_callback
7073
Base.LibGit2.credentials_cb

0 commit comments

Comments
 (0)