Add a method of git() that bypasses cmd parsing. (#36)

Project.toml

@@ -1,7 +1,7 @@
 name = "Git"
 uuid = "d7ba0133-e1db-5d97-8f8c-041e4b3a1eb2"
 authors = ["Dilum Aluthge", "contributors"]
-version = "1.1.0"
+version = "1.2.0"
 
 [deps]
 Git_jll = "f8c6e375-362e-5223-8a59-34ff63f689eb"

README.md

@@ -22,6 +22,29 @@ julia> using Git
 julia> run(`$(git()) clone https://github.com/JuliaRegistries/General`)
 ```
 
+This can equivalently be written with explicitly split arguments as
+
+```
+julia> run(git(["clone", "https://github.com/JuliaRegistries/General"]))
+```
+
+to bypass the parsing of the command string.
+
+To read a single line of output from a git command you can use `readchomp`,
+
+```
+julia> cd("General")
+
+julia> readchomp(`$(git()) remote get-url origin`)
+"https://github.com/JuliaRegistries/General"
+```
+
+and `readlines` for multiple lines.
+
+```
+julia> readlines(`$(git()) log`)
+```
+
 ## Acknowledgements
 
 - This work was supported in part by National Institutes of Health grants U54GM115677, R01LM011963, and R25MH116440. The content is solely the responsibility of the authors and does not necessarily represent the official views of the National Institutes of Health.

src/Git.jl

@@ -1,3 +1,8 @@
+"""
+The Git module allows you to use command-line Git in your Julia
+packages. This is implemented with the `git` function, which returns a
+`Cmd` object giving access to command-line Git.
+"""
 module Git
 
 import Git_jll

src/git_function.jl

@@ -6,8 +6,16 @@ Return a `Cmd` for running Git.
 ## Example
 
 ```julia
-julia> run(`$(git()) clone https://github.com/JuliaRegistries/General`)
+julia> run(`\$(git()) clone https://github.com/JuliaRegistries/General`)
 ```
+
+This can equivalently be written with explicitly split arguments as
+
+```
+julia> run(git(["clone", "https://github.com/JuliaRegistries/General"]))
+```
+
+to bypass the parsing of the command string.
 """
 function git(; adjust_PATH::Bool = true, adjust_LIBPATH::Bool = true)
     @static if Sys.iswindows()
@@ -33,3 +41,9 @@ function git(; adjust_PATH::Bool = true, adjust_LIBPATH::Bool = true)
         return addenv(original_cmd, env_mapping...)::Cmd
     end
 end
+
+function git(args::AbstractVector{<:AbstractString}; kwargs...)
+    cmd = git(; kwargs...)
+    append!(cmd.exec, args)
+    return cmd
+end

test/runtests.jl

@@ -30,7 +30,7 @@ end
     withtempdir() do tmp_dir
         @test !isdir("Git.jl")
         @test !isfile(joinpath("Git.jl", "Project.toml"))
-        run(`$(git()) clone https://github.com/JuliaVersionControl/Git.jl`)
+        run(git(["clone", "https://github.com/JuliaVersionControl/Git.jl"]))
         @test isdir("Git.jl")
         @test isfile(joinpath("Git.jl", "Project.toml"))
     end