Skip to content
Snippets Groups Projects
Verified Commit 7a0e2c3d authored by nfontrod's avatar nfontrod
Browse files

Readme.md: update

parent a22f31db
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 60 additions and 36 deletions
Readme.md
+ 60
− 36
View file @ 7a0e2c3d
......@@ -30,7 +30,7 @@ If you want to share your borg folder whith gblk `clone`, `push` and `pull`, `rs
To install gblk run the following command:
```bash
```sh
cargo install --git https://gitbio.ens-lyon.fr/LBMC/hub/git_borg_linker
```
......@@ -41,7 +41,7 @@ gblk is meant to be used inside a project using git as a version control system.
To sum up gblk must be used in a folder having this minimal structure:
```bash
```sh
project
├── .git
└── results
......@@ -318,16 +318,17 @@ Gblk as two commands `mount` and `unmount` that can be used to respectively
mount your borg archives into the `.mount` folder of the project directory or
unmount them.
> **⚠ Important note** : When the borg archive is mounted, borg is locked ! It
> mean that you can get the following error message if you forget to unmount a
> borg acrchive when calling a **borg command** on it:
> ` Failed to create/acquire thelock ..` . To resolve it just use
> `gblkt umount`. gblk will **silently unmount** the borg archive before
> commit, checkout, pre-checkout and mount commands.
::: {.callout-important}
When the borg archive is mounted, borg is locked ! It
means that you can get the following error message if you forget to unmount a borg acrchive when calling a **borg command** on it:
` Failed to create/acquire thelock ..`.
To resolve it just use `gblkt umount`. gblk will **silently unmount** the borg archive before `commit`, `checkout`, `pre-checkout` and `mount` commands.
:::
## gblk mount usage:
```text
```sh
gblk-mount
Mount an old file/directory from one or multiple archive named afert git commits into the .mount
folder inside de project directory
......@@ -383,13 +384,13 @@ $ gblk umount # unmount the archive mounted into `.mount` directory
If we have two archive containing a file named `file.txt` and we want to
direclty compare them in a similar way as `git diff`, then we can enter:
```
```sh
gblk mount -p 'results/file.txt' --diff
```
The differences between the two files will be displayed with delta:
```
```sh
Δ .mount/cfdc/results/lol.txt ⟶ .mount/4ec196bb/results/lol.txt
────────────────────────────────────────────────────────────────────────
......@@ -427,7 +428,7 @@ available for an image diff: PNG, JPEG, BMP, ICO, SVG, PDF
Let's say, we have one image named im1.png inside the last commit. to compare it with the image im1.png in the result folder, you can type:
```
```sh
gblk mount --last 1 -p 'results/im1.png' --diff
```
......@@ -489,7 +490,7 @@ Note that this command doesn't actually free disk space. You have to use `gblk c
To display the help of gblk delete, run the following command:
```bash
```sh
gblk delete -h # -h for compact help, --help for a more exhaustive help
```
......@@ -550,7 +551,7 @@ If the amount of parts that need compaction is big the `.borg folder`, this comm
Sometimes, you want to only keep a small number archives of your `results` folder to save some space. If you always want to keep all backups from last week and one backup per month for 5 month, it can tedious to always remember the prune archive doing that:
```
```sh
gblk prune --keep-within '7d' --keep-monthly 5 --dry-run
```
......@@ -558,13 +559,15 @@ You may want to put those settings in a local or in a global configuration file
gblk provide a way to do that by using the borg configuration file `.borg/config` as a local configuration file and the `~/.gblkconfig` file as a global configuration file.
> Note: **If both the local and global configuration files contain gblk settings used for pruning, only the local settings are used..**
::: {.callout-note}
**If both the local and global configuration files contain gblk settings used for pruning, only the local settings are used..**
:::
### Add new settings in configuration file
To **add or update** settings in the local configuration file you can use the following command:
```
```sh
gblk config add <KEY> <VALUE> [--global]
```
......@@ -575,11 +578,13 @@ And `VALUE` corresponds to the value to associate with the key
Check [borg documentation](https://borgbackup.readthedocs.io/en/stable/usage/prune.html) to know what those arguments do. You can also run the command `gblk prune --help` to see a description of those arguments.
> Note: you can also use the `KEY` by replacing the '-' by an '_'. gblk will have the same behavior.
::: {.callout-note}
You can also use the `KEY` by replacing the '-' by an '_'. gblk will have the same behavior.
:::
For example, to keep **all backups from last week and one backup per month for 5 month**, you must run the following command:
```
```sh
gblk config add keep-within '7d'
gblk config add keep-monthly 5
```
......@@ -597,7 +602,9 @@ keep_within = '7d'
keep_monthly = 5
```
> Note: The '-' in keep_within is replaced by an underscore inside the configuration file
::: {.callout-note}
The '-' in keep_within is replaced by an underscore inside the configuration file
:::
## Remove gblk settings used for pruning
......@@ -625,10 +632,13 @@ To do the same thing with the global configuration file just add `--global` at t
Finnaly, to prune your results archives using the settings defined in the global or local configuration you can use the following command:
```
```sh
gblk config prune [OPTION]
```
> Note: **If both the local and global configuration files contain gblk settings used for pruning, only the local settings are used..**
::: {.callout-note}
**If both the local and global configuration files contain gblk settings used for pruning, only the local settings are used..**
:::
You can see what option you can add to your command with
......@@ -653,11 +663,15 @@ Filtering options:
# 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 other or update it with chnages done by others.
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 other or update it with changes done by others.
> Note: The choice of sharing the complete archive folder `.borg` was made to always benefits from borg's deduplication
::: {.callout-note}
The choice of sharing the complete archive folder `.borg` was made to always benefits from borg's deduplication
:::
> **⚠ Warning**: The way of duplicating and storing an archive folder is not the way borg was intended to be used. Indeed the replacment 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.
::: {.callout-warning}
The way of duplicating and storing an archive folder is not the way borg was intended to be used. Indeed the replacment 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.
:::
## Remotes
......@@ -665,7 +679,9 @@ In order to be able to share your archived results in the `.borg` folder, you us
- *local* remotes are only defined for a given project
- *global* remotes are available for any gblk projects. It can be usefull if you often want to store your gblk results on a same location.
> Note: If a *global* remote have the same name as a *local* remote, only the local remote can be used for this project.
::: {.callout-note}
If a *global* remote have the same name as a *local* remote, only the local remote can be used for this project.
:::
The file that will store the local remotes is `.borg/.gblkconfig` inside the root of your project folder.
The file that will sotre the global remote is `~/.gblkconfig` in your `HOME` folder
......@@ -680,7 +696,7 @@ gblk remote --help
It display the following message.
```
```sh
gblk-remote
This command can be used to add a new remote for push and pull commands
......@@ -713,8 +729,9 @@ To define a globally defined remote you can enter the following commands:
gblk remote add KEY VALUE --global
```
> Note: This command can also be used to uptade the value of an existing commands
::: {.callout-note}
This command can also be used to uptade the value of an existing commands
:::
## Removing a remote
......@@ -740,7 +757,7 @@ It will display *locally* and *globally* defined remotes. Note that only unmaske
Here is an example of what the commands can display:
```
```sh
local: /path/to_destination_folder
psmn: psmn:/home/user/test_folder (global)
```
......@@ -755,12 +772,12 @@ You can see that *globally* defined remote are tagged with `(global)`.
This command 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
gblk clone [HOSTNAME:]PATH
```
Where `PATH` is the 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
......@@ -768,9 +785,12 @@ PATH
└── README
```
> Note: clone muste be used with a *path* and not a remote name.
::: {.callout-note}
Clone muste be used with a *path* and not a remote name.
:::
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`
......@@ -826,6 +846,7 @@ Where `KEY` is the name of a *global* or *local* remote. **Path are not supporte
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:
......@@ -836,8 +857,9 @@ Here are the steps that the push command execute:
- 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*
> **⚠ Warning**: The pull command can delete s old archive inside it !
::: {.callout-warning}
The pull command can delete s old archive inside it !
:::
# Pull command
......@@ -852,6 +874,7 @@ gblk pull KEY
Where `KEY` is the name of a *global* or *local* remote. **Path are not supported!**.
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.
......@@ -861,8 +884,9 @@ Here are the steps that the pull command execute:
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.
> Note: The pull command saves the inital content of the `.borg` folder inside the `.tmp` directory. **Remember to delte it if the pull is sucessful
::: {.callout-note}
The pull command saves the inital content of the `.borg` folder inside the `.tmp` directory. **Remember to delte it if the pull is sucessful
:::
# Gblk restore command
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment