From 62d8671dce857a281060fd74e8f85df6110d8b07 Mon Sep 17 00:00:00 2001 From: kshyatt Date: Fri, 25 Aug 2017 15:44:47 -0700 Subject: [PATCH] Docs for a bunch of git blame stuff --- base/libgit2/blame.jl | 16 ++++++++++++++++ base/libgit2/consts.jl | 8 ++++++++ base/libgit2/types.jl | 14 ++++++++++++++ doc/src/devdocs/libgit2.md | 3 +++ 4 files changed, 41 insertions(+) diff --git a/base/libgit2/blame.jl b/base/libgit2/blame.jl index a0dee7bb25f02..ee239a0ce0ae0 100644 --- a/base/libgit2/blame.jl +++ b/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 diff --git a/base/libgit2/consts.jl b/base/libgit2/consts.jl index 39597dc90bdc9..eb7e31bf71de4 100644 --- a/base/libgit2/consts.jl +++ b/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) diff --git a/base/libgit2/types.jl b/base/libgit2/types.jl index 1b29c3417d5e3..3f5387dbbd5ee 100644 --- a/base/libgit2/types.jl +++ b/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 diff --git a/doc/src/devdocs/libgit2.md b/doc/src/devdocs/libgit2.md index d49f9a7294157..e3e831fc15fc9 100644 --- a/doc/src/devdocs/libgit2.md +++ b/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