diff --git a/slides/slides.qmd b/slides/slides.qmd index 3bcb7c2abd524fc8017dcdacbb85a124a431df8e..0f6c83601e63e88ee919182f6711f50fe4e85800 100644 --- a/slides/slides.qmd +++ b/slides/slides.qmd @@ -949,7 +949,6 @@ A global configuration file can also be defined by gblk automatically at `~/.gbl ## gblk configuration file - Pruning options -**gblk pruning options (1/4)** To *add or update* settings for pruning in the local or global configuration file you can use the command: @@ -1012,4 +1011,319 @@ $ gblk config show keep_within = '7d' $ gblk config rm keep-within # 'gblk config rm keep_within' also works $ gblk config show -``` \ No newline at end of file +No local pruning options defined +``` + +Use `gblk config show --global` to see the globally defined pruning options + +## gblk configuration file - Pruning options {.unnumbered .unlisted} + +To prune your results archives using the options defined in the global or local configuration you can use the following command: + +```sh +gblk config prune [OPTION] +``` + +::: {.callout-important } +If no options are defined, an error will be thrown: + +```sh +$ gblk config prune --dry-run --list +error: No global and local options defined for pruning! +``` +::: + + +You can see what option you can add to your command with + +```sh +$ gblk config prune --help +``` +<p><p> + + +## gblk configuration file - Pruning options {.unnumbered .unlisted} + +::: {.callout-note} +If both local and global pruning options are defined, only the *local settings are used* +::: + +Example: + +```bash +gblk config add keep-within '2d' +gblk config add keep-weekly 3 --global +gblk config prune --dry-run --list +``` +```console +Keeping archive (rule: within #1): 248a2... Tue, 2023-02-14 09:39:10 [ef885...] +Keeping archive (rule: within #2): 964fe... Mon, 2023-02-13 09:12:50 [fef70...] +Would prune: df0eb... Fri, 2023-02-10 16:15:56 [c9409...] +``` +```bash +gblk config rm keep-within +gblk config prune --dry-run --list +``` +```console +Keeping archive (rule: weekly #1): 248a2... Tue, 2023-02-14 09:39:10 [ef885...] +Would prune: 964fe... Mon, 2023-02-13 09:12:50 [fef70...] +Keeping archive (rule: weekly #2): df0eb... Fri, 2023-02-10 16:15:56 [c9409...] +``` +<p><p> + +## Sharing gblk repositories + + +When you produce some results for a particular project, you may want to *share them with others* who are working with you. With gblk you can share your `.borg` repository with others or update it with chnages done by others. + +::: {.callout-note} +The choice of sharing the complete archive folder `.borg` was made to always benefits from borg's deduplication +::: + +::: {.callout-warning} +The way of *duplicating and storing an archive folder* is not the way *borg was intended to be used*. Indeed the replacement of a borg repository by an older one *is considered suspicious* and **borg blocks the executions of its commands for this archive**. See [this page](https://borgbackup.readthedocs.io/en/stable/faq.html?highlight=attack#this-is-either-an-attack-or-unsafe-warning) for details. +::: + +## gblk configuration file - Remotes + +To share your archived results, you can use *remotes* like in git. + +Remotes can be defined *globally* or *locally*: + +- *local* remotes are only defined for a given project +- *global* remotes are available for any gblk projects. Useful if to store your gblk results on a same location. + +::: {.callout-note} +If a *global* remote have the same name as a *local* remote, only the local remote can be used for this project. + +- *local* remotes are defined in the file `.borg/.gblkconfig` +- *global* remotes are defined in the file `~/.gblkconfig` +::: + +## gblk configuration file - Remotes {.unnumbered .unlisted} + +A remote is defined by a: + +- A *name*: used to identify the remotes +- A *path*: the path pointed by the remote + + - Can be defined as `[USER@]HOSTNAME:PATH` + - Host defined in `ssh config file` can be used + - The *path* must point to an existing directory + +## gblk configuration file - Remotes {.unnumbered .unlisted} + +**Add a new remote** + +To *add a new local remote* you can use the following command: + +```sh +gblk remote add KEY VALUE +``` + +- `KEY`: The name of the remote +- `VALUE`: The URL it points to. + +To define a globally defined remote you can enter the following command: + +```sh +gblk remote add KEY VALUE --global +``` +::: {.callout-note} +This command can also be used to uptade the value of an existing commands +::: + +## gblk configuration file - Remotes {.unnumbered .unlisted} + +**Remove a remote** + +To remove a remote named `KEY` you can use this command + +```sh +gblk remote rm KEY +``` + +You can add the flag `--global` at the end of the previous command to remove a globally defined remote. + +```sh +gblk remote rm KEY --global +``` +<p><p> + +## gblk configuration file - Remotes {.unnumbered .unlisted} + +**Displaying remotes** + + +```sh +gblk remote show +``` + +It will display *locally* and *globally* defined remotes. + +::: {.callout-note} +Only unmasked `globally` remotes are displayed (e.g the global remotes that don't share a name with any local remotes). +::: + + +::: {.callout-tip} + +## Example + + +```sh +gblk remote add psmn psmn:/home/user/test_folder_local +gblk remote add psmn psmn:/home/user/test_folder_global --global +gblk remote add psmn2 psmn:/home/user/test_folder_global2 --global +gblk remote show +``` +```console +psmn: psmn:/home/user/test_folder_local +psmn2: psmn:/home/user/test_folder_global2 (global) +``` + +You can see that *globally* defined remotes are tagged with `(global)`. +::: + +## gblk clone + +Can be used after a `git clone` command. + +If a gblk archive folder is available for the project, then you can execute the following command: + +```sh +gblk clone [HOSTNAME:]PATH [--compression] [--hooks] +``` +- [HOSTNAME:]: Optional, can be defined as `USER@HOSTNAME`. Hosts defined in `ssh config file` can be used +- `PATH`: path of a gblk archive folder. The `PATH` must point to a folder with this structure (corresponding to a borg remote archive): + +```sh +PATH +├── archive_list +├── config +├── data +└── README +``` +::: {.callout-important} +clone must be used with a *path* and *not a remote name*. +::: + +## gblk clone {.unnumbered .unlisted} + +Here are the steps that the clone command execute: + +1. Checks if `.borg` folder already exists. +2. Checks if the remote directory already exists and contains `data`, `config` and `archive_file` inside. +3. Copies with rsync the remote directory into `.borg` +4. Creates the local config file `.borg/.gblkconfig` using the name of the archive +5. Add a local remote called `origin` into the local config file +6. Creates a `.gitignore` and a `results/.gitignore` + +:::: {.columns} +::: {.column width="50%"} +```sh +# .gitignore +.borg +.tmp +.mount +``` +::: + +::: {.column width="50%"} +```sh +# results/.gitignore +* +!.gitignore + + +``` +::: +:::: + +7. Create hooks if needed + +## gblk push + +To copy the content of the `.borg` folder into another location you can use the `push` command like this: + +```sh +gblkt push KEY +``` + +Where `KEY` is the name of a *global* or *local* remote. **Path are not supported!**. + +::: {.callout-warning} +The push command might deletes old archives inside the remote archive folder folder ! +::: + + +## gblk push {.unnumbered .unlisted} + +::: {.callout layout="minimal"} +Here are the steps that the push command execute: + +1. Checks if the *remote folder* (defined by the remote) exists +2. Checks if the *remote archive folder* (folder that will contains the archives) exits. It corresponds to the *path* of the remote and the name of the folder containing the `.borg` folder. +3. If it doesn't exists: + - go to step 5 +4. If it exists: + - Checks if the borg id is the same between the remote and the local borg archive. Stops the command if not. + - gblk uses the `archive_list` file on the *remote archive folder* to compare it with the current archive list saved and show to the users the differences between the remote and the local archive lists. + - Then it asks the user whether or not to continue the push. +5. Copies with rsync the content of the current `.borg` folder into the *remote archive folder* +::: + +## gblk pull + +The pull commands allow to replace the content of your `.borg` archive into a remote folder. + +It can be used with the following command: + +```sh +gblk pull KEY +``` + +Where `KEY` is the name of a *global* or *local* remote. **Path are not supported!**. + +::: {.callout-note} +The pull commands saves the inital content of the `.borg` folder inside the `.tmp` directory. **Remember to delete it if the pull is sucessful +::: + + +## gblk pull {.unnumbered .unlisted} + + +::: {.callout layout="minimal"} + +Here are the steps that the pull command execute: + +1. Checks if the *remote folder* (defined by the remote) exists +2. Checks if the *remote archive folder* (folder that will contains the archives) exits. If it doesn't, stops the pull. +3. Checks if the borg id is the same between the remote and the local borg archive folder. Stops the pull if not. +4. gblk uses the `archive_list` file on the *remote archive folder* to compare it with the current archive list saved and show to the users the differences between the remote and the local archive lists. +5. Asks the user whether or not to continue the pull +6. Saves and clean `.borg` folder. The content of the old `.borg` folder is saved inside the `.tmp` folder and can be recovered with the `gblk restore` command if something goes wrong afterward. +7. Copies with rsync the content of the *remote archive folder* into the current `.borg` folder. +8. Removes borg manifest timestamp and the cache associated to the current project archive folder. +::: + +## gblk restore + +This command can be used to restore your 'old' `.borg` folder the way it was before the last pull command. It can help to recover from an error that occured during the pull. + +To restore your old `.borg` folder, enter the command + +```sh +gblk restore +``` +<p><p> + +## gblk clean + + +After a `pull` or after using `gblk mount` with the `--diff` flag, temporary files are stored inside the `.tmp` directory. You can remove those with the command: + +```sh +gblk clean +``` +<p><p> \ No newline at end of file diff --git a/slides/style.css b/slides/style.css index d058bd5b6e55f787e86495859749fa17930863ef..d54f11958159f0f8cb57813b06e84026f257f2e3 100644 --- a/slides/style.css +++ b/slides/style.css @@ -96,4 +96,11 @@ height: 1.2rem; background-size: 1.2rem, 1.2rem; margin-top: 0.7rem; +} + +.reveal nav ul { + font-size: 1.1em; + columns: 2; + -webkit-columns: 2; + -moz-columns: 2; } \ No newline at end of file