slides/slides.qmd: udpate

slides/slides.qmd

@@ -165,14 +165,174 @@ The `results` folder is *mandatory* to use gblk.
 This is this folder that will be tracked by gblk.
 
 
-## Git Borg Linker - Init
+## Git Borg Linker - init
 
 Let's see how gblk works with an example:
 
 ```bash
 $ mkdir test_gblk; cd test_gblk
-$ mkdir results; src
+$ mkdir results src
 $ git init
 ```
 
-Initialize gblk to start using it: Done with `gblk init`
\ No newline at end of file
+Initialize gblk to start using it: Done with `gblk init`.
+
+This commands create a folder named `.borg` at the root of the project repository. This is where the *`results` folder backups will be stored*.
+
+```bash
+gblk-init
+Initialize a borg repository inside a git project
+
+USAGE:
+    gblk init [OPTIONS]
+
+OPTIONS:
+    -c, --compression <COMPRESSION>    The compression to use automatically at each commit if hooks are create [default: lz4]
+    -h, --help                         Print help information
+    -H, --hooks                        If specified, hooks are created inside `.git/hooks repository`
+    -m, --mode <MODE>                  The checkout mode used by gblk automatically after a git checkout: soft or hard. This option is only used if hooks are created. The hard mode will delete every file in your results folder and extract those corresponding to the commit targeted by the checkout [default: hard]
+```
+
+Available compressions: no, lz4, zstd, zlib or lzma.
+
+## Git Borg Linker - init {.unnumbered .unlisted}
+
+gblk can optionally create git hooks (with `gblk init` command or `create-hooks`) to automatically execute commands:
+
+::: {.callout-note icon=false appearance="minimal"}
+
+- After a commit to automatically save you data (execute `gblk commit` automatically)
+- After a checkout to:
+  1. Revert the checkout
+  2. Check if there is unsaved/missing data in the `results` folder (compared to the archive of the current commit). If so, stops the checkout.
+  3. Perform git checkout
+  4. Perform a gblk checkout (restore your `results` folder as it was at the destination commit).
+:::
+
+The hooks created by those commands can be found in `.git/hooks`
+folder and are name `post-commit` and `post-checkout`.
+
+::: {.callout-note icon=true}
+
+The command `gblk create-hooks` can be used to create hooks if gblk was initialised without the `--hook` arguments
+
+:::
+
+## Git Borg Linker - init {.unnumbered .unlisted}
+
+`gblk init --hooks` and `create-hooks` commands will also create 3 git aliases:
+
+::: {.callout-note icon=false appearance="minimal"}
+-  `co`: for *checkout*. It allow to make the git checkout quiet (because it will be reverted)
+- `conh`: For *checkout*. It allow to make a checkout without using the hooks. It is useful to bypass the check of unsaved/missing data in the `results` folder. *You have to combine it with `gblk checkout ---mode hard`* to checkout your `results` folder to the new current commit.
+- `cnh`: For *commit*. It allows to make a simple git commit without saving your result repository (may lead to data loss)
+:::
+
+::: {.callout-note icon=true}
+Those aliases are valid only *for the current project*. They can be found in the file `.git/config`
+:::
+
+Finally, gblk init creates `.gitignore` and `results/.gitignore` files
+
+::: {layout-ncol=2}
+
+```bash
+# .gitignore
+.borg
+.tmp
+.mount
+```
+
+```bash
+# results/.gitignore
+*
+!.gitignore
+
+
+```
+:::
+
+## Git Borg Linker - init {.unnumbered .unlisted .big-margin}
+
+Let's init gblk with hooks:
+
+```bash
+$ gblk init --hooks
+borg repository initialised at .borg
+```
+
+Creates an empty `.borg` repository were the backups of the `results` folder will be saved.
+
+## Git Borg Linker - commit
+
+Let's add a code that will produce a result file.
+
+```bash
+$ echo "echo 'result line' > results/result.txt" > src/script.sh # creates a script file
+$ bash src/script.sh # creation of a results/result.txt
+$ git add src/script.sh && git commit -m "src/script.sh: initial commit" # commit the change
+Repository: /.../test_gblk/.borg
+Archive name: df0eb55ce43fa48b652340183b5f9cc69daa2350
+Archive fingerprint: c9409d26c4a0e1e60c28b2db0dca17a82e802fc9f2dcb6ed0ffe9bfb69f62679
+Time (start): Fri, 2023-02-10 16:15:56
+Time (end):   Fri, 2023-02-10 16:15:56
+Duration: 0.00 seconds
+Number of files: 2
+Utilization of max. archive size: 0%
+------------------------------------------------------------------------------
+                       Original size      Compressed size    Deduplicated size
+This archive:                  623 B                565 B                565 B
+All archives:                   25 B                 31 B                835 B
+
+                       Unique chunks         Total chunks
+Chunk index:                       4                    4
+------------------------------------------------------------------------------
+[master (commit racine) df0eb55] src/script.sh: initial commit
+ 1 file changed, 1 insertion(+)
+ create mode 100644 src/script.sh
+```
+
+## Git Borg Linker - commit {.unnumbered .unlisted}
+
+Because a *post-commit* hook was created, the command
+
+```bash
+git commit -m "src/script.sh: initial commit"
+```
+
+Is equivalent to:
+
+```bash
+git commit -m "src/script.sh: initial commit" # commit the change
+gblk commit # commit the results, we have to use this command after commit if gblk hooks are not enabled
+```
+
+A backup *with the name current git commit* was created. We can use `gblk list` to list the backups.
+```
+<b>
+
+## Git Borg Linker - list
+
+The `gblk list` command lists all backups inside the `.borg` folder
+
+```bash
+$ gblk list
+b1da0e305c906fb242bc8... Mon, 2022-06-13 15:47:24 [2960...]
+$ git rev-parse --verify HEAD # Show current commit
+b1da0e305c906fb242bc8...
+```
+
+```bash
+$ gblk list -h
+gblk-list
+List the content of the .borg archive
+
+USAGE:
+    gblk list [OPTIONS]
+
+OPTIONS:
+    -a, --archive <ARCHIVE>    If set list the files in this archive [default: ]
+    -f, --first <N>            consider first N archives [default: 0]
+    -h, --help                 Print help information
+    -l, --last <N>             consider last N archives [default: 0]
+```
\ No newline at end of file

slides/style.css

@@ -82,3 +82,10 @@
     color: rgb(0, 0, 0);
     font-family: monospace;
 }
+
+.reveal .callout.callout-captioned .callout-icon::before {
+    width: 1.2rem;
+    height: 1.2rem;
+    background-size: 1.2rem, 1.2rem;
+    margin-top: 0.7rem;
+}
\ No newline at end of file