Skip to content

Commit

Permalink
Merge pull request #20503 from JuliaLang/ksh/docgit5
Browse files Browse the repository at this point in the history
MORE docs for libgit2
  • Loading branch information
kshyatt authored Feb 8, 2017
2 parents 8fd280f + 33b725a commit 1b7a684
Show file tree
Hide file tree
Showing 3 changed files with 70 additions and 0 deletions.
27 changes: 27 additions & 0 deletions base/libgit2/repository.jl
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,12 @@ function GitRepo(path::AbstractString)
return GitRepo(repo_ptr_ptr[])
end

"""
LibGit2.GitRepoExt(path::AbstractString, flags::Cuint = Cuint(Consts.REPOSITORY_OPEN_DEFAULT))
Opens a git repository at `path` with extended controls (for instance, if the current
user must be a member of a special access group to read `path`).
"""
function GitRepoExt(path::AbstractString, flags::Cuint = Cuint(Consts.REPOSITORY_OPEN_DEFAULT))
separator = @static is_windows() ? ";" : ":"
repo_ptr_ptr = Ref{Ptr{Void}}(C_NULL)
Expand All @@ -39,13 +45,26 @@ function cleanup(r::GitRepo)
end
end

"""
LibGit2.init(path::AbstractString, bare::Bool=false) -> GitRepo
Opens a new git repository at `path`. If `bare` is `false`,
the working tree will be created in `path/.git`. If `bare`
is `true`, no working directory will be created.
"""
function init(path::AbstractString, bare::Bool=false)
repo_ptr_ptr = Ref{Ptr{Void}}(C_NULL)
@check ccall((:git_repository_init, :libgit2), Cint,
(Ptr{Ptr{Void}}, Cstring, Cuint), repo_ptr_ptr, path, bare)
return GitRepo(repo_ptr_ptr[])
end

"""
LibGit2.head_oid(repo::GitRepo) -> GitHash
Lookup the object id of the current HEAD of git
repository `repo`.
"""
function head_oid(repo::GitRepo)
head_ref = head(repo)
try
Expand All @@ -55,6 +74,14 @@ function head_oid(repo::GitRepo)
end
end

"""
LibGit2.headname(repo::GitRepo)
Lookup the name of the current HEAD of git
repository `repo`. If `repo` is currently
detached, returns the name of the HEAD it's
detached from.
"""
function headname(repo::GitRepo)
with(head(repo)) do href
if isattached(repo)
Expand Down
17 changes: 17 additions & 0 deletions base/libgit2/status.jl
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
# This file is a part of Julia. License is MIT: http://julialang.org/license

"""
LibGit2.GitStatus(repo::GitRepo; status_opts=StatusOptions())
Collect information about the status of each file in the git
repository `repo` (e.g. is the file modified, staged, etc.).
`status_opts` can be used to set various options, for instance
whether or not to look at untracked files or whether to include
submodules or not.
"""
function GitStatus(repo::GitRepo; status_opts=StatusOptions())
stat_ptr_ptr = Ref{Ptr{Void}}(C_NULL)
@check ccall((:git_status_list_new, :libgit2), Cint,
Expand All @@ -23,6 +32,14 @@ function Base.getindex(status::GitStatus, i::Integer)
return unsafe_load(entry_ptr)
end

"""
LibGit2.status(repo::GitRepo, path::String)
Lookup the status of the file at `path` in the git
repository `repo`. For instance, this can be used
to check if the file at `path` has been modified
and needs to be staged and committed.
"""
function status(repo::GitRepo, path::String)
status_ptr = Ref{Cuint}(0)
ret = ccall((:git_status_file, :libgit2), Cint,
Expand Down
26 changes: 26 additions & 0 deletions base/libgit2/tag.jl
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# This file is a part of Julia. License is MIT: http://julialang.org/license

"""
LibGit2.tag_list(repo::GitRepo) -> Vector{String}
Get a list of all tags in the git repository `repo`.
"""
function tag_list(repo::GitRepo)
sa_ref = Ref(StrArrayStruct())
@check ccall((:git_tag_list, :libgit2), Cint,
Expand All @@ -9,11 +14,27 @@ function tag_list(repo::GitRepo)
res
end

"""
LibGit2.tag_delete(repo::GitRepo, tag::AbstractString)
Remove the git tag `tag` from the repository `repo`.
"""
function tag_delete(repo::GitRepo, tag::AbstractString)
@check ccall((:git_tag_delete, :libgit2), Cint,
(Ptr{Void}, Cstring, ), repo.ptr, tag)
end

"""
LibGit2.tag_create(repo::GitRepo, tag::AbstractString, commit; kwargs...)
Create a new git tag `tag` (e.g. `"v0.5"`) in the repository `repo`, at
the commit `commit`.
The keyword arguments are:
* `msg::AbstractString=""`: the message for the tag.
* `force::Bool=false`: if `true`, existing references will be overwritten.
* `sig::Signature=Signature(repo)`: the tagger's signature.
"""
function tag_create(repo::GitRepo, tag::AbstractString, commit::Union{AbstractString,AbstractGitHash};
msg::AbstractString = "",
force::Bool = false,
Expand All @@ -30,6 +51,11 @@ function tag_create(repo::GitRepo, tag::AbstractString, commit::Union{AbstractSt
return oid_ptr[]
end

"""
LibGit2.name(tag::GitTag)
The name of `tag` (e.g. `"v0.5"`).
"""
function name(tag::GitTag)
str_ptr = ccall((:git_tag_name, :libgit2), Cstring, (Ptr{Void}, ), tag.ptr)
str_ptr == C_NULL && throw(Error.GitError(Error.ERROR))
Expand Down

0 comments on commit 1b7a684

Please sign in to comment.