Add docstrings for Git commands [ci skip]

Author: ararslan

src/Git.jl

@@ -12,6 +12,12 @@ depsjl = joinpath(dirname(@__FILE__), "..", "deps", "deps.jl")
 isfile(depsjl) ? include(depsjl) : error("Git.jl not properly installed. " *
     "Please run\nPkg.build(\"Git\")")
 
+"""
+    Git.dir([d])
+
+Return the path to the default `.git` for the given repository directory, or the
+path to use in place of the default `.git`.
+"""
 function dir(d)
     g = joinpath(d,".git")
     isdir(g) && return g
@@ -27,18 +33,34 @@ function git(d)
     `$gitcmd --git-dir=$work_tree` : `$gitcmd --work-tree=$work_tree --git-dir=$git_dir`
 end
 
+"""
+    Git.cmd(args; dir="")
+
+Return a Git command from the given arguments, acting on the repository given in `dir`.
+"""
 cmd(args::Cmd; dir="") = `$(git(dir)) $args`
 run(args::Cmd; dir="", out=STDOUT) = Base.run(pipeline(cmd(args,dir=dir), out))
 readstring(args::Cmd; dir="") = Base.readstring(cmd(args,dir=dir))
 readchomp(args::Cmd; dir="") = Base.readchomp(cmd(args,dir=dir))
 
+"""
+    Git.success(args; dir="")
+
+Determine whether the Git command using the given arguments on the given repository
+executed successfully.
+"""
 function success(args::Cmd; dir="")
     g = git(dir)
     Base.readchomp(`$g rev-parse --is-bare-repository`) == "false" &&
         Base.run(`$g update-index -q --really-refresh`)
     Base.success(`$g $args`)
 end
 
+"""
+    Git.version()
+
+Return the version of Git being used by the package.
+"""
 function version()
     vs = split(readchomp(`version`), ' ')[3]
     ns = split(vs, '.')
@@ -75,6 +97,11 @@ immutable State
     work::Compat.UTF8String
 end
 
+"""
+    Git.snapshot(; dir="")
+
+Return a `State` object that consisting of a snapshot of the given repository.
+"""
 function snapshot(; dir="")
     head = readchomp(`rev-parse HEAD`, dir=dir)
     index = readchomp(`write-tree`, dir=dir)
@@ -90,6 +117,11 @@ function snapshot(; dir="")
     State(head, index, work)
 end
 
+"""
+    Git.restore(s; dir="")
+
+Restore the given repository to the state `s`.
+"""
 function restore(s::State; dir="")
     run(`reset -q --`, dir=dir)               # unstage everything
     run(`read-tree $(s.work)`, dir=dir)       # move work tree to index
@@ -99,6 +131,12 @@ function restore(s::State; dir="")
     run(`reset -q --soft $(s.head)`, dir=dir) # restore head
 end
 
+"""
+    Git.transact(f; dir="")
+
+Attempt to execute the function `f`. If this fails, the repository is restored to its
+state prior to execution.
+"""
 function transact(f::Function; dir="")
     state = snapshot(dir=dir)
     try f() catch
@@ -107,6 +145,11 @@ function transact(f::Function; dir="")
     end
 end
 
+"""
+    Git.is_ancestor_of(a, b; dir="")
+
+Determine whether the commit `a` is an ancestor of the commit `b` in the given repository.
+"""
 function is_ancestor_of(a::AbstractString, b::AbstractString; dir="")
     A = readchomp(`rev-parse $a`, dir=dir)
     readchomp(`merge-base $A $b`, dir=dir) == A
@@ -115,6 +158,11 @@ end
 const GITHUB_REGEX =
     r"^(?:git@|git://|https://(?:[\w\.\+\-]+@)?)github.com[:/](([^/].+)/(.+?))(?:\.git)?$"i
 
+"""
+    Git.set_remote_url(url; remote="origin", dir="")
+
+Add a remote `remote` to the given repository from the URL `url`.
+"""
 function set_remote_url(url::AbstractString; remote::AbstractString="origin", dir="")
     run(`config remote.$remote.url $url`, dir=dir)
     m = match(GITHUB_REGEX,url)
@@ -123,6 +171,11 @@ function set_remote_url(url::AbstractString; remote::AbstractString="origin", di
     push != url && run(`config remote.$remote.pushurl $push`, dir=dir)
 end
 
+"""
+    Git.normalize_url(url)
+
+Normalize the given URL to a valid GitHub repository URL.
+"""
 function normalize_url(url::AbstractString)
     m = match(GITHUB_REGEX,url)
     m === nothing ? url : "git://github.com/$(m.captures[1]).git"