Renew asciinema/screencasts

[rugk]

Created with borg v1.1.0, so more up-to-date and split into different
parts (install, basic, advanced)…
Fixes #669

As @enkore did before I also tried to clean up the JSON files manually a bit afterwards (also shortened the tar.gz creation e.g.), but a second look on them cannot hurt. 😃

Also a general suggestion: Maybe create a new asciinema account called "BorgBackup" or something general (as this GitHub organisation) in order not to tie the screencasts to a single user/member. (Also so one can see they are "official".)

install

link: https://asciinema.org/a/D2fMg1HPUgLMxGPIYuRoYjlQC
title: Install the BorgBackup (borg) standalone binary
for description:

This shows how to install the backup utility BorgBackup (short: borg) on any (Linux) device. It follows the official guide and shows how to verify and install the binary.

suggested thumbnail frame: 40s

basic

link: https://asciinema.org/a/aQGBdQzxpD4LiFNOITfleCqIv
title: BorgBackup (borg) – basic usage
for description:

This shows the basic commands to get started with the backup utility BorgBackup (short: borg).
It shows:

• how to create a repository
• how to do a backup, i.e. creating an archive
• some advantages of borg in multiple backup runs
• how to list the content of an archive
• extracting an archive (or, a part of it)
• creating a remote backup via ssh

suggested thumbnail frame: 126s (02:06)

advanced

link: https://asciinema.org/a/vpiMAH0nxexgHW9Ba5tV4ZWZ0
title: BorgBackup (borg) – advanced usage
for description:

This shows some advanced commands of the backup utility BorgBackup (short: borg).
It shows:

advanced creation:

• how to avoid having to enter the repo/credentials every time you use a borg command
• using placeholders in archive creation
• backing up different contents into one repository
• backing up via STDIN/backing up block devices

useful commands:

• showing information about the last archive/backup run
• exporting the encryption key

maintenance:

• checking/repairing a broken backup
• pruning old backups

restore:

• showing the diff between two backups/archives
• exporting archives as tar(.gz) files
• mounting archives

suggested thumbnail frame: 218s (03:38)

[enkore]

Also a general suggestion: Maybe create a new asciinema account called "BorgBackup" or something general (as this GitHub organisation) in order not to tie the screencasts to a single user/member. (Also so one can see they are "official".)

(An existing asciicast can easily be uploaded to another account using asciinema upload, the same goes for editing asciicasts)

[rugk]

(An existing asciicast can easily be uploaded to another account using asciinema upload, the same goes for editing asciicasts)

That's interesting. I did not know that you can edit them and upload to the same URL. (Or did you want to say something different?)
In any case, that was not my point. My point was: Just create a new account/mail at asciinema, so that below the screencast "created by BorgBackup" is written and not "created by ThomasWaldmann".

[enkore]

The asciinema command generally only works with the account you logged into.

(On the current demo page there is no extra text - but we can also easily host it ourselves, so the JSON recordings would simply live as regular files in git, see borgbackup.github.io repository).

[rugk]

The asciinema command generally only works with the account you logged into.

I know, I've used it enough in the last two days, but your still not answering my question…

but we can also easily host it ourselves,

Ah, so do you actually plan this?
With my description etc. I of course referred to the official site, but in any case some descriptive text (also for search engines/SEO, etc.) is useful.

On the current demo page there is no extra text

Never saw this page before, BTW. I only saw your linked screenshots in Readme etc. and thought you'll stay with this system… But for me it does not matter.
Only maybe the screencasts can also be found on asciinema by other users or so and it could attract people to borg… don't know…

[ThomasWaldmann]

thanks for updating this stuff!

some issues:

"basic" link is same as "install" link.

also, i watched the asciinema casts and they contained a lot of typos / small errors. so, if they are already fixed, please provide new links. if not, please watch them and fix the obvious stuff yourself (including removing typo fixes you did interactively from the json file, so one does not replay the typos), then update the links to the fixed version. i'll review then again and point you to any remaining issues (if any).

[rugk]

"basic" link is same as "install" link.

Upps, yeah. I've corrected it.

contained a lot of typos / small errors

I thought some small typos would make the more natural/human… 😉

watch them and fix the obvious stuff yourself

Okay, I'll do.

[rugk]

I updated the install script. Sorry for adding the dev/temp files there, I'll remove them in the next commit.

[ThomasWaldmann]

• don't use dark grey on black for comments, low contrast, hard to read
• don't use a 1.0 repo for the remote repo, so you won't get the ugly traceback because of the missing rpc method

[enkore]

You can probably edit the latter out. The former should be possible by editing the ANSI escapes in the JSON.

[rugk]

I did both and also removed many typos, so everything looks smooth. I updated the asciinema links in the OP.

[ThomasWaldmann]

typos in advanced:

• "several envorimental variables"
• "have indefite disk space"
• "When actually execute it in a script, "
• "You can even even mount an archive:"

After fixing these, maybe watch the videos again.

There were also some cases of plural vs. singular and some interactively fixed typos ("ü").

[rugk]

Thanks, I've fixed them.

("ü").

Yeah, already fixed that in the previous commit.

"You can even even mount an archive:"

Also already fixed, could not find this.

I also looked at advanced again and could not find any further issues.

[enkore]

*environment (without -al)

[rugk]

Ah, right, fixed.

[rugk]

Should I fake/post-edit the screenshots to show the new line in borg info?

[ThomasWaldmann]

@rugk if you like... (not required, over time there might be other differences also).

[rugk]

Okay, edited. Also updated the asciinema links.

[ThomasWaldmann]

btw, if one compares these screencasts with the old one, one notices:

• new: more colorful :)
• new: the json is mostly unreadable / unworkable due to lots of escape sequences :(
• old: pretty clean json (few escape seqs), but screen looks boring black/white
• old: typing most of the stuff looks more natural
• new: copy & pasting bigger stuff less so. harder to follow.

[rugk]

Yeah, but one thing causes the other one (i.e. colors make the JSON more unreadable, because of the needed escape sequences).

I did not copy & paste anything (except of one time), I just used the auto-completion (up key) and entered the completed comments before, so that they could be "autocompleted".
If I had written each sentence again and again I would not only have gone nuts (I always recorded them in one piece – maybe that is a thing I learned/can change in the future), but also would have done a horribly big amount of typos or similar things.
Everything else is also hand-craftedtyped… 😃 And the comments are just, … well comments.
I also thought one can read these comments pretty fast – in contrast to me writing them in a really slow pace. And no one wants to see how I write comments (not that fascinating🙄), but how I execute borg commands. 😄

Some more differences, BTW:

• new: we have a structure with three different parts and the advanced part is structured too
• new: more commands, "basic" really begins with the basics (borg help)
• new: real-life examples, i.e. ssh backup and local backup on an external storage device instead of "just some random dir" and useful use cases of borg commands (combined with standard Linux things) are shown (STDIN backup or grepping for a particular file)
• new: sentences written "properly" with a capital letter at the beginning
• new: short PS1 ($) instead of long, useless, username+password+cwd…
• old/new: the best sentences ("Wow, this was a lot faster!") were adopted 😄
• old: nostalgia for old borg version :)

BTW thanks to "autocompleting" the comments, you can mostly easily search and edit them as they have no escape sequences inside itself.

[ThomasWaldmann]

Ah, interesting idea of previously feeding the stuff so it can be autocompleted.
But when watching this, it looks a bit strange as it begins with typing and then whoosh, the rest comes quickly.

[rugk]

BTW now I understood this thing about special files and also see why borg create --read-special --progress --stats ::specialbackup /dev/loop0 (I also had this is the script) does not work. --read-special only considers/also includes special files in the backup right? May need a clarification in the docs. (Should I open a new issue for that?)

[rugk]

So I've fixed your issues and two or three other typos I also spotted when doing so.
Links updated. (but, BTW, you can also use asciinema play – just set your terminal to the right size before)

[ThomasWaldmann]

ah, you are right about encryption, we require manual choice now (since 1.1).

about --read-special: not sure what you mean by "does not work". It opens and reads the contents of special files (like it was a regular file), not just backing up the device file itself (== its metadata).

[rugk]

Ah so borg create --read-special --progress --stats ::specialbackup /dev/loop0 should work? Should it work in the same way as I am doing in the asciinema via stdin? If so, okay… If not, also okay… maybe I'll have a look at this later.

[ThomasWaldmann]

It should work, creating a regular file called dev/loop0 in your backup that has all the contents read from /dev/loop0. It's especially nice if you backup multiple block devices, like snapshot LVs from lvm for example.

[rugk]

Okay, it does indeed work…

[ThomasWaldmann]

basic:

• looks defect at 1:07 (archive name appears on next line first)
• still "--compression lz4"

advanced:

• looks defect at 2:31

can you do the next iterations on your own?

just look at the stuff you produce (twice, if once is not enough), the stuff I keep finding is rather obvious.

update the online versions after you don't find anything yourself any more, for a final review.

[ThomasWaldmann]

some more ideas in #2909 (as this is new, it is not required to complete the bounty you've already started, but we could put another bounty on it).

[rugk]

You are just that good of finding tiny tasks. And as I said I already fixed some other flaws in the previous iterations.

And as you see messing with the files again and again may introduce some display issues. Now I also understand why: In the lines you mentioned I removed the compression thing. That results in the "new line"/line break being at a different position and in these issues. So maybe I have to rerecord that piece… 😒 (fortunately, only that part)

some more ideas in #2909

If I knew this previously, I would have certainly considered it… 😐

[ThomasWaldmann]

would be nice if we had this in a good state at 1.1.0 release time (next is rc2).

[rugk]

Is it really necessary the remove that --compression lz4? I mean it shows an option to the user, at least.
And thing is, if I remove it from the second command too, now, I also break it (as the defect you mentioned previously). So reverting the affected parts of the last commit would be easier…

[ThomasWaldmann]

@rugk ok, revert it. we can fix it in a later iteration.

[rugk]

Asciinema links updated.

[ThomasWaldmann]

basic thumbnail: 2:26s (so one sees the dedup)

[ThomasWaldmann]

can you do the backport to 1.1-maint branch also?

[ThomasWaldmann]

crap. i'll fix the tons of fix, fix, fix in master first.....

ok, done.

[enkore]

Thanks for bearing with us! :)

[rugk]

can you do the backport to 1.1-maint branch also?

Yeah, I hope I did it correctly: #2937