Skip to content

Commit

Permalink
Merge pull request #23455 from JuliaLang/ksh/docblame
Browse files Browse the repository at this point in the history
Docs for a bunch of git blame stuff
  • Loading branch information
kshyatt authored Aug 27, 2017
2 parents a059bd7 + 62d8671 commit f6e0fca
Show file tree
Hide file tree
Showing 4 changed files with 41 additions and 0 deletions.
16 changes: 16 additions & 0 deletions base/libgit2/blame.jl
Original file line number Diff line number Diff line change
@@ -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,
Expand All @@ -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
Expand Down
8 changes: 8 additions & 0 deletions base/libgit2/consts.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
14 changes: 14 additions & 0 deletions base/libgit2/types.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions doc/src/devdocs/libgit2.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit f6e0fca

Please sign in to comment.