From e08e64fdf2832c1585d16066f8b8fe983845f7f3 Mon Sep 17 00:00:00 2001
From: Abel Soares Siqueira <abel.siqueira@esciencecenter.nl>
Date: Fri, 7 Jun 2024 19:10:15 +0200
Subject: [PATCH] =?UTF-8?q?feat:=20=F0=9F=8E=B8=20Implement=20update=20fun?=
 =?UTF-8?q?ction=20and=20add=20to=20guide?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Create a update wrapper calling the internal Copier update. The
overwrite=true argument needs to be passed to mimic the CLI behaviour.
Updates the guide with specific information to update.

✅ Closes: #113
---
 docs/src/10-full-guide.md | 31 ++++++++++++++++++++++++++++++-
 src/COPIERTemplate.jl     | 20 ++++++++++++++++++++
 test/runtests.jl          | 28 ++++++++++++++++++++++++++++
 3 files changed, 78 insertions(+), 1 deletion(-)

diff --git a/docs/src/10-full-guide.md b/docs/src/10-full-guide.md
index b5e2ecce..57c2f27a 100644
--- a/docs/src/10-full-guide.md
+++ b/docs/src/10-full-guide.md
@@ -129,7 +129,36 @@ Now, go to [Setting up your package](@ref) to check what you still need to confi
 
 ### [Updating](@id updating_package)
 
-WIP. Tracked in issue #113.
+To update the package, simply call
+
+```julia-repl
+julia> COPIERTemplate.update()
+```
+
+You will be asked the relevant questions of the package as if you had applied it.
+The big differences are:
+
+- It will only apply the things that are new since you last applied/updated
+- It will remember previous answer.
+
+!!! tip "Change previous answers"
+    You can change your previous answers. In other words, if you though something was not mature enough in the past, but you are more confident in that now, you can adopt it now.
+
+As with the first application, you need to run `pre-commit run -a` to fix the unavoidable linting and formatting issues.
+Check the modifications in the relevant linter and formatting files, if you changed them manually, before doing it, though.
+
+```bash
+pre-commit run -a
+```
+
+The underlying package `copier` will use `git` to apply the differences and it will overwrite whatever files it finds in the way.
+Since `git` is mandatory, the changes will be left for you to review.
+
+!!! warning "Review the changes"
+    I repeat, the changes will be left for you to review.
+    Don't just add them blindly, because some of your modifications can and will be overwritten.
+
+If you need some help with undoing some of these changes, I recommend using a graphical interface.
 
 ## Setting up your package
 
diff --git a/src/COPIERTemplate.jl b/src/COPIERTemplate.jl
index e0f97b84..39766ecd 100644
--- a/src/COPIERTemplate.jl
+++ b/src/COPIERTemplate.jl
@@ -52,6 +52,26 @@ function generate(dst_path, data::Dict = Dict(); kwargs...)
   generate("https://github.com/abelsiqueira/COPIERTemplate.jl", dst_path, data; kwargs...)
 end
 
+"""
+    update([data]; kwargs...)
+    update(dst_path[, data]; kwargs...)
+
+Run the update command of copier, updating the `dst_path` (or the current path if omitted) with a new version of the template with a new version of the template.
+
+The `data` argument is a dictionary of answers (values) to questions (keys) that can be used to bypass some of the interactive questions.
+
+## Keyword arguments
+
+The keyword arguments are passed directly to the internal [`Copier.update`](@ref).
+"""
+function update(dst_path, data::Dict = Dict(); kwargs...)
+  Copier.update(dst_path, data; overwrite = true, kwargs...)
+end
+
+function update(data::Dict = Dict(); kwargs...)
+  Copier.update(".", data; overwrite = true, kwargs...)
+end
+
 """
     data = _read_data_from_existing_path(dst_path)
 
diff --git a/test/runtests.jl b/test/runtests.jl
index 87f82745..7ea2432a 100644
--- a/test/runtests.jl
+++ b/test/runtests.jl
@@ -111,6 +111,34 @@ end
   end
 end
 
+@testset "Compare COPIERTemplate.update vs copier CLI update" begin
+  mktempdir(TMPDIR; prefix = "cli_") do dir_copier_cli
+    run(`copier copy --defaults --quiet $min_bash_args $template_url $dir_copier_cli`)
+    cd(dir_copier_cli) do
+      run(`git init`)
+      run(`git add .`)
+      run(`git config user.name "Test"`)
+      run(`git config user.email "test@test.com"`)
+      run(`git commit -q -m "First commit"`)
+    end
+    run(`copier update --defaults --quiet $bash_args $dir_copier_cli`)
+
+    mktempdir(TMPDIR; prefix = "update_") do tmpdir
+      COPIERTemplate.generate(tmpdir, template_minimum_options; defaults = true, quiet = true)
+      cd(tmpdir) do
+        run(`git init`)
+        run(`git add .`)
+        run(`git config user.name "Test"`)
+        run(`git config user.email "test@test.com"`)
+        run(`git commit -q -m "First commit"`)
+      end
+      COPIERTemplate.update(tmpdir, template_options; defaults = true, quiet = true)
+
+      test_diff_dir(tmpdir, dir_copier_cli)
+    end
+  end
+end
+
 @testset "Testing copy, recopy and rebase" begin
   mktempdir(TMPDIR; prefix = "cli_") do dir_copier_cli
     run(`copier copy --quiet $bash_args $template_path $dir_copier_cli`)