From 792106abc3b6b4291394de449e75990aba17ad9c Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Mon, 5 Feb 2024 15:48:15 -0400 Subject: [PATCH] improve special remote docs Sponsored-by: Dartmouth College's DANDI project --- doc/git-annex-testremote.mdwn | 4 +- doc/special_remotes.mdwn | 48 +++++++++++-------- ..._edd0a4e9894d07e7bae9fef1fe4acf6d._comment | 14 ++++++ 3 files changed, 45 insertions(+), 21 deletions(-) create mode 100644 doc/todo/documentation__58___improve_on_special_remotes/comment_1_edd0a4e9894d07e7bae9fef1fe4acf6d._comment diff --git a/doc/git-annex-testremote.mdwn b/doc/git-annex-testremote.mdwn index cc03b769db..77f7aebaed 100644 --- a/doc/git-annex-testremote.mdwn +++ b/doc/git-annex-testremote.mdwn @@ -16,7 +16,9 @@ not altered), although it may perform expensive data transfers. It's best to make a new remote for testing purposes. While the test tries to clean up after itself, if the remote being tested had a bug, -the cleanup might fail, leaving test data in the remote. +the cleanup might fail, leaving test data in the remote. Also, +some special remotes don't support removal of data that has been stored +in them, so test data won't be able to be cleaned up when testing those. Testing will use the remote's configuration, automatically varying the chunk sizes, and with simple shared encryption disabled and enabled, diff --git a/doc/special_remotes.mdwn b/doc/special_remotes.mdwn index f776605423..74f473045e 100644 --- a/doc/special_remotes.mdwn +++ b/doc/special_remotes.mdwn @@ -79,18 +79,30 @@ git annex move --to specialremote large files when your local drive is getting full, and then git annex move the files back when free space is again available. You could have one repository copy files to a special remote, and then git annex get them on another repository, to transfer the -files between computers that do not communicate directly. - -The git-annex assistant makes it easy to set up rsync remotes using this -last scenario, which is referred to as a transfer repository, and arranges -to drop files from the transfer repository once they have been transferred -to all known clients. +files between computers that do not communicate directly. None of these use cases are particular to particular special remote types. Most special remotes can all be used in these and other ways. It largely doesn't matter for your use what underlying transport the special remote uses. +## Setting up a special remote + +To create a new special remote, use +[[git-annex initremote|git-annex-initremote]]. See the documentation for +the special remote you want to use for details about configuration and +examples of how to initremote it. + +Once a special remote has been created, other clones of the repository can +also enable it, by using [[git-annex enableremote|git-annex-enableremote]] +with the same name that was used to initialize it. (Run the command without +any name to get a list of available special remotes.) + +Initializing or enabling a special remote adds it as a remote of your git +repository. You can't use git commands like `git pull` with the remote +(usually, there are exceptions like [[git-lfs]]), but you can use git-annex +commands. + ## Unused content on special remotes Over time, special remotes can accumulate file content that is no longer @@ -108,20 +120,16 @@ on special remotes, instead use `git annex unused --from`. Example: $ git annex dropunused --from mys3 1 dropunused 12948 (from mys3...) ok +## Removing special remotes + +Like git remotes, a special remote can be removed from your repository +by using `git remote remove`. Note that does not delete the special remote, +or prevent other repositories from enabling or using it. + ## Testing special remotes To make sure that a special remote is working correctly, you can use the -`git annex testremote` command. This expects you to have set up the remote -as usual, and it then runs a lot of tests, using random data. It's -particularly useful to test new implementations of special remotes. - -By default it will upload and download files of around 1MiB to the remote -it tests; the `--size` parameter can adjust it to test using smaller files. - -It's safe to use this command even when you're already storing data in a -remote; it won't touch your existing files stored on the remote. - -For most remotes, it also won't bloat the remote with any data, since -it cleans up the stuff it uploads. However, the bup, ddar, and tahoe -special remotes don't support removal of uploaded files, so be careful -with those. +[[git annex testremote|git-annex-testremote]] command. This expects you to +have set up the remote as usual, and it then runs a lot of tests, using +random data. It's particularly useful to test new implementations of +special remotes. diff --git a/doc/todo/documentation__58___improve_on_special_remotes/comment_1_edd0a4e9894d07e7bae9fef1fe4acf6d._comment b/doc/todo/documentation__58___improve_on_special_remotes/comment_1_edd0a4e9894d07e7bae9fef1fe4acf6d._comment new file mode 100644 index 0000000000..634aaa1970 --- /dev/null +++ b/doc/todo/documentation__58___improve_on_special_remotes/comment_1_edd0a4e9894d07e7bae9fef1fe4acf6d._comment @@ -0,0 +1,14 @@ +[[!comment format=mdwn + username="joey" + subject="""comment 1""" + date="2024-02-05T19:44:16Z" + content=""" +The walkthrough has enough to get a user started in the right direction +in . + +I don't know if is a +good entry point for a user to learn the basics of what they are. It's +mostly a list, and I doubt most readers make it past the list. + +I have expanded it to mention the main commands. +"""]]