WIP: Generating and storing a patch (#80)

* Generating and storing a patch

* rename commit to gitcommit

* added docs

* Fix @tag! and tagsave after tag! argument re-ordering

* minor doc

Author: mauro3

CHANGELOG.md

@@ -1,5 +1,7 @@
 # 0.8.0
 * **[BREAKING]** : Slightly changed how `produce_or_load` uses `path` and interacts with `savename`, to better incorporate the changes done in version 0.6.0. `prefix` is now also supported.
+* `tag!` and co now also store the git diff patch if the repo is dirty (#80).
+* **[BREAKING]** : `tag!` now saves the commit information into a field `gitcommit` instead of just `commit`.
 
 # 0.7.1
 * `projectdir()` now warns if no project (other than the standard one) is

docs/src/save.md

@@ -31,9 +31,10 @@ For reproducibility reasons (and also to not go insane when asking "HOW DID I GE
 To this end we have some functions that can be used to ensure reproducibility:
 
 ```@docs
-gitdescribe
 tag!
 @tag!
+gitdescribe
+DrWatson.gitpatch
 ```
 
 Please notice that `tag!` will operate in place only when possible. If not possible then a new dictionary is returned. Also (importantly) these functions will **never error** as they are most commonly used when saving simulations and this could risk data not being saved!

src/saving_files.jl

@@ -27,7 +27,7 @@ See also [`savename`](@ref).
 """
 produce_or_load(c, f; kwargs...) = produce_or_load("", c, f; kwargs...)
 function produce_or_load(path::String, c, f;
-    tag::Bool = true, gitpath = projectdir(), loadfile = true,
+    tag::Bool = true, gitpath = projectdir(), storepatch = true, loadfile = true,
     suffix = "bson", prefix = default_prefix(c),
     force = false, verbose = true, kwargs...)
 
@@ -50,7 +50,7 @@ function produce_or_load(path::String, c, f;
         try
             mkpath(dirname(s))
             if tag
-                tagsave(s, file, false, gitpath)
+                tagsave(s, file, false, gitpath, storepatch)
             else
             wsave(s, copy(file))
         end
@@ -70,13 +70,13 @@ end
 #                             tag saving                                       #
 ################################################################################
 """
-    tagsave(file::String, d::Dict [, safe = false, gitpath = projectdir()])
+    tagsave(file::String, d::Dict [, safe = false, gitpath = projectdir(), storepatch = true])
 First [`tag!`](@ref) dictionary `d` and then save `d` in `file`.
 If `safe = true` save the file using [`safesave`](@ref).
 """
 tagsave(file, d, p::String) = tagsave(file, d, false, p)
-function tagsave(file, d, safe = false, gitpath = projectdir(), s = nothing)
-    d2 = tag!(d, gitpath, s)
+function tagsave(file, d, safe = false, gitpath = projectdir(), storepatch = true, s = nothing)
+    d2 = tag!(d, gitpath, storepatch, s)
     mkpath(dirname(file))
     if safe
         safesave(file, copy(d2))
@@ -91,9 +91,9 @@ end
 Same as [`tagsave`](@ref) but also add a field `script` that records
 the local path of the script that called `@tagsave`, see [`@tag!`](@ref).
 """
-macro tagsave(file, d, safe::Bool = false, gitpath = projectdir())
+macro tagsave(file, d, safe::Bool = false, gitpath = projectdir(), storepatch = true)
     s = QuoteNode(__source__)
-    :(tagsave($(esc(file)), $(esc(d)), $(esc(safe)), $(esc(gitpath)), $s))
+    :(tagsave($(esc(file)), $(esc(d)), $(esc(safe)), $(esc(gitpath)), $(esc(storepatch)), $s))
 end
 
 ################################################################################

src/saving_tools.jl

@@ -65,18 +65,47 @@ function gitdescribe(gitpath = projectdir())
     return c
 end
 
-@deprecate current_commit gitdescribe
+"""
+    gitpatch(gitpath = projectdir())
+
+Generates a patch describing the changes of a dirty repository
+compared to its last commit; i.e. what `git diff HEAD` produces.
+"""
+function gitpatch(gitpath = projectdir())
+    try
+        repo = LibGit2.GitRepo(gitpath)
+    catch er
+        @warn "The directory ('$gitpath') is not a Git repository, "*
+              "returning `nothing` instead of a patch."
+        return nothing
+    end
+    # tree = LibGit2.GitTree(repo, "HEAD^{tree}")
+    # diff = LibGit2.diff_tree(repo, tree)
+    # now there is no way to generate the patch with LibGit2.jl.
+    # Instead use commands:
+    patch = read(`git --git-dir=$(gitpath)/.git diff HEAD`, String)
+    return patch
+end
 
 """
-    tag!(d::Dict, gitpath = projectdir()) -> d
-Tag `d` by adding an extra field `commit` which will have as value
+    tag!(d::Dict, gitpath = projectdir(), storepatch = true) -> d
+Tag `d` by adding an extra field `gitcommit` which will have as value
 the [`gitdescribe`](@ref) of the repository at `gitpath` (by default
-the project's gitpath). Do nothing if a key `commit` already exists or
-if the Git repository is not found.
+the project's gitpath). Do nothing if a key `gitcommit` already exists
+or if the Git repository is not found. If the git repository is dirty,
+i.e. there are un-commited changes, then the output of `git diff HEAD`
+is stored in the field `gitpatch`.  Note that patches for binary files
+are not stored.
 
 Notice that if `String` is not a subtype of the value type of `d` then
-a new dictionary is created and returned. Otherwise the operation
-is inplace (and the dictionary is returned again).
+a new dictionary is created and returned. Otherwise the operation is
+inplace (and the dictionary is returned again).
+
+To restore a repository to the state of a particular model-run do:
+- checkout the relevant commit with `git checkout xyz` where
+xyz is the value stored
+- apply the patch `git apply patch`, where the string stored
+in the `gitpatch` field needs to be written to the file `patch`.
 
 ## Examples
 ```julia
@@ -87,25 +116,32 @@ Dict{Symbol,Int64} with 2 entries:
 
 julia> tag!(d)
 Dict{Symbol,Any} with 3 entries:
-  :y      => 4
-  :commit => "96df587e45b29e7a46348a3d780db1f85f41de04"
-  :x      => 3
+  :y => 4
+  :gitcommit => "96df587e45b29e7a46348a3d780db1f85f41de04"
+  :x => 3
 ```
 """
-function tag!(d::Dict{K, T}, gitpath = projectdir(), source = nothing) where {K, T}
+function tag!(d::Dict{K, T}, gitpath = projectdir(), storepatch = true, source = nothing) where {K, T}
 
     c = gitdescribe(gitpath)
-    c === nothing && return d
-    if haskey(d, K("commit"))
-        @warn "The dictionary already has a key named `commit`. We won't "*
+    patch = gitpatch(gitpath)
+    c === nothing && return d # gitpath is not a git repo
+    if haskey(d, K("gitcommit"))
+        @warn "The dictionary already has a key named `gitcommit`. We won't "*
         "add any Git information."
         return d
     end
     if String <: T
-        d[K("commit")] = c
+        d[K("gitcommit")] = c
+        if patch!=""
+            d[K("gitpatch")] = patch
+        end
     else
         d = Dict{K, promote_type(T, String)}(d)
-        d[K("commit")] = c
+        d[K("gitcommit")] = c
+        if patch!=""
+            d[K("gitpatch")] = patch
+        end
     end
     if source != nothing
         if haskey(d, K("script"))
@@ -135,14 +171,14 @@ julia> d = Dict(:x => 3)Dict{Symbol,Int64} with 1 entry:
 
 julia> @tag!(d) # running from a script or inline evaluation of Juno
 Dict{Symbol,Any} with 3 entries:
-  :commit => "618b72bc0936404ab6a4dd8d15385868b8299d68"
+  :gitcommit => "618b72bc0936404ab6a4dd8d15385868b8299d68"
   :script => "test\\stools_tests.jl#10"
   :x      => 3
 ```
 """
-macro tag!(d, gitpath = projectdir())
+macro tag!(d, gitpath = projectdir(), storepatch = true)
     s = QuoteNode(__source__)
-    :(tag!($(esc(d)), $(esc(gitpath)), $s))
+    :(tag!($(esc(d)), $(esc(gitpath)), $(esc(storepatch)), $s))
 end
 
 """

test/savefiles_tests.jl

@@ -21,15 +21,15 @@ end
 t = f(simulation)
 tagsave(savename(simulation, "bson"), t, findproject())
 file = load(savename(simulation, "bson"))
-@test "commit" ∈ keys(file)
-@test file["commit"] |> typeof == String
+@test "gitcommit" ∈ keys(file)
+@test file["gitcommit"] |> typeof == String
 rm(savename(simulation, "bson"))
 
 t = f(simulation)
 @tagsave(savename(simulation, "bson"), t, false, findproject())
 file = load(savename(simulation, "bson"))
-@test "commit" ∈ keys(file)
-@test file["commit"] |> typeof == String
+@test "gitcommit" ∈ keys(file)
+@test file["gitcommit"] |> typeof == String
 @test "script" ∈ keys(file)
 @test file["script"] |> typeof == String
 @test file["script"] == joinpath("test", "savefiles_tests.jl#29")

test/stools_tests.jl

@@ -14,17 +14,17 @@ d2 = Dict("x" => 3, "y" => 4)
 for d in (d1, d2)
     d = tag!(d, dirname(@__DIR__))
 
-    @test haskey(d, keytype(d)(:commit))
-    @test d[keytype(d)(:commit)] |> typeof <: String
+    @test haskey(d, keytype(d)(:gitcommit))
+    @test d[keytype(d)(:gitcommit)] |> typeof <: String
 end
 
 # @tag!
 for d in (d1, d2)
     d = @tag!(d, @__DIR__)
-    @test !haskey(d, keytype(d)(:commit))
+    @test !haskey(d, keytype(d)(:gitcommit))
 
     d = @tag!(d, dirname(@__DIR__))
-    @test d[keytype(d)(:commit)] |> typeof <: String
+    @test d[keytype(d)(:gitcommit)] |> typeof <: String
     @test d[keytype(d)(:script)][1:4] == "test"
 end