From cd9fa80125d69bdb9e2d2eff497b082c25d055e0 Mon Sep 17 00:00:00 2001 From: kshyatt Date: Mon, 26 Jun 2017 12:52:02 -0500 Subject: [PATCH 1/2] Add docs for the diff.jl methods --- base/libgit2/diff.jl | 52 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/base/libgit2/diff.jl b/base/libgit2/diff.jl index c01e2268d841b..7e15d3c5d4b10 100644 --- a/base/libgit2/diff.jl +++ b/base/libgit2/diff.jl @@ -11,7 +11,18 @@ function Base.unsafe_convert(::Type{Ptr{DiffOptionsStruct}}, rr::Tuple{Ref{DiffO Base.unsafe_convert(Ptr{DiffOptionsStruct}, first(rr)) end +""" + diff_tree(repo::GitRepo, tree::GitTree, pathspecs::AbstractString=""; cached::Bool=false) +Generates a [`GitDiff`](@ref) between `tree` (which will be used for the "old" +side of the [`DiffDelta`](@ref)) and `repo` (which will be used for the "new" side). +If `repo` is `cached`, calls [`git_diff_tree_to_index`](https://libgit2.github.com/libgit2/#HEAD/group/diff/git_diff_tree_to_index). +The `cached` version is generally used to examine the diff for staged changes from one +commit to the next. If `cached` is `false`, calls +[`git_diff_tree_to_workdir_with_index`](https://libgit2.github.com/libgit2/#HEAD/group/diff/git_diff_tree_to_workdir_with_index). +This compares the current working directory against the [`GitIndex`](@ref) and can, +for example, be used to examine the changes in staged files before a commit. +""" function diff_tree(repo::GitRepo, tree::GitTree, pathspecs::AbstractString=""; cached::Bool=false) diff_ptr_ptr = Ref{Ptr{Void}}(C_NULL) if cached @@ -26,6 +37,16 @@ function diff_tree(repo::GitRepo, tree::GitTree, pathspecs::AbstractString=""; c return GitDiff(repo, diff_ptr_ptr[]) end +""" + diff_tree(repo::GitRepo, oldtree::GitTree, newtree::GitTree) + +Generates a [`GitDiff`](@ref) between `oldtree` (which will be used for the "old" +side of the [`DiffDelta`](@ref)) and `newtree` (which will be used for the "new" +side of the `DiffDelta`). Equivalent to [`git_diff_tree_to_tree`](https://libgit2.github.com/libgit2/#HEAD/group/diff/git_diff_tree_to_tree). +This can be used to generate a diff between two commits. For instance, it could +be used to compare a commit made 2 months ago with the current latest commit, or +to compare a commit on another branch with the current latest commit on `master`. +""" function diff_tree(repo::GitRepo, oldtree::GitTree, newtree::GitTree) diff_ptr_ptr = Ref{Ptr{Void}}(C_NULL) @check ccall((:git_diff_tree_to_tree, :libgit2), Cint, @@ -34,6 +55,13 @@ function diff_tree(repo::GitRepo, oldtree::GitTree, newtree::GitTree) return GitDiff(repo, diff_ptr_ptr[]) end +""" + GitDiffStats(diff::GitDiff) + +Get the diff statistics from the `GitDiff` `diff`. This object records a summary +of changes made across the `diff`. In particular, it records how many files were +changed, how many insertions were made, and how many deletions were made. +""" function GitDiffStats(diff::GitDiff) diff_stat_ptr_ptr = Ref{Ptr{Void}}(C_NULL) @check ccall((:git_diff_get_stats, :libgit2), Cint, @@ -42,14 +70,38 @@ function GitDiffStats(diff::GitDiff) return GitDiffStats(diff.owner, diff_stat_ptr_ptr[]) end +""" + files_changed(diff_stat::GitDiffStats) -> Csize_t + +Returns how many files were changed (added/modified/deleted) in the [`GitDiff`](@ref) +summarized by `diff_stat`. The result may vary depending on the [`DiffOptionsStruct`](@ref) +used to generate the parent `GitDiff` of `diff_stat` (for instance, whether ignored files +are to be included or not). +""" function files_changed(diff_stat::GitDiffStats) return ccall((:git_diff_stats_files_changed, :libgit2), Csize_t, (Ptr{Void},), diff_stat.ptr) end +""" + insertions(diff_stat::GitDiffStats) -> Csize_t + +Returns the total number of insertions (lines added) in the [`GitDiff`](@ref) +summarized by `diff_stat`. The result may vary depending on the [`DiffOptionsStruct`](@ref) +used to generate the parent `GitDiff` of `diff_stat` (for instance, whether ignored files +are to be included or not). +""" function insertions(diff_stat::GitDiffStats) return ccall((:git_diff_stats_insertions, :libgit2), Csize_t, (Ptr{Void},), diff_stat.ptr) end +""" + deletions(diff_stat::GitDiffStats) -> Csize_t + +Returns the total number of deletions (lines removed) in the [`GitDiff`](@ref) +summarized by `diff_stat`. The result may vary depending on the [`DiffOptionsStruct`](@ref) +used to generate the parent `GitDiff` of `diff_stat` (for instance, whether ignored files +are to be included or not). +""" function deletions(diff_stat::GitDiffStats) return ccall((:git_diff_stats_deletions, :libgit2), Csize_t, (Ptr{Void},), diff_stat.ptr) end From 6277330dcc5822a3965c91bb46829ab4d474a705 Mon Sep 17 00:00:00 2001 From: kshyatt Date: Mon, 26 Jun 2017 14:35:00 -0500 Subject: [PATCH 2/2] [ci skip] refs and imperatives --- base/libgit2/diff.jl | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/base/libgit2/diff.jl b/base/libgit2/diff.jl index 7e15d3c5d4b10..a4a172be9d302 100644 --- a/base/libgit2/diff.jl +++ b/base/libgit2/diff.jl @@ -14,7 +14,7 @@ end """ diff_tree(repo::GitRepo, tree::GitTree, pathspecs::AbstractString=""; cached::Bool=false) -Generates a [`GitDiff`](@ref) between `tree` (which will be used for the "old" +Generate a [`GitDiff`](@ref) between `tree` (which will be used for the "old" side of the [`DiffDelta`](@ref)) and `repo` (which will be used for the "new" side). If `repo` is `cached`, calls [`git_diff_tree_to_index`](https://libgit2.github.com/libgit2/#HEAD/group/diff/git_diff_tree_to_index). The `cached` version is generally used to examine the diff for staged changes from one @@ -40,7 +40,7 @@ end """ diff_tree(repo::GitRepo, oldtree::GitTree, newtree::GitTree) -Generates a [`GitDiff`](@ref) between `oldtree` (which will be used for the "old" +Generate a [`GitDiff`](@ref) between `oldtree` (which will be used for the "old" side of the [`DiffDelta`](@ref)) and `newtree` (which will be used for the "new" side of the `DiffDelta`). Equivalent to [`git_diff_tree_to_tree`](https://libgit2.github.com/libgit2/#HEAD/group/diff/git_diff_tree_to_tree). This can be used to generate a diff between two commits. For instance, it could @@ -58,9 +58,9 @@ end """ GitDiffStats(diff::GitDiff) -Get the diff statistics from the `GitDiff` `diff`. This object records a summary -of changes made across the `diff`. In particular, it records how many files were -changed, how many insertions were made, and how many deletions were made. +Get the diff statistics from the [`GitDiff`](@ref) `diff`. This object records a +summary of changes made across the `diff`. In particular, it records how many +files were changed, how many insertions were made, and how many deletions were made. """ function GitDiffStats(diff::GitDiff) diff_stat_ptr_ptr = Ref{Ptr{Void}}(C_NULL) @@ -73,7 +73,7 @@ end """ files_changed(diff_stat::GitDiffStats) -> Csize_t -Returns how many files were changed (added/modified/deleted) in the [`GitDiff`](@ref) +Return how many files were changed (added/modified/deleted) in the [`GitDiff`](@ref) summarized by `diff_stat`. The result may vary depending on the [`DiffOptionsStruct`](@ref) used to generate the parent `GitDiff` of `diff_stat` (for instance, whether ignored files are to be included or not). @@ -85,7 +85,7 @@ end """ insertions(diff_stat::GitDiffStats) -> Csize_t -Returns the total number of insertions (lines added) in the [`GitDiff`](@ref) +Return the total number of insertions (lines added) in the [`GitDiff`](@ref) summarized by `diff_stat`. The result may vary depending on the [`DiffOptionsStruct`](@ref) used to generate the parent `GitDiff` of `diff_stat` (for instance, whether ignored files are to be included or not). @@ -97,7 +97,7 @@ end """ deletions(diff_stat::GitDiffStats) -> Csize_t -Returns the total number of deletions (lines removed) in the [`GitDiff`](@ref) +Return the total number of deletions (lines removed) in the [`GitDiff`](@ref) summarized by `diff_stat`. The result may vary depending on the [`DiffOptionsStruct`](@ref) used to generate the parent `GitDiff` of `diff_stat` (for instance, whether ignored files are to be included or not).