mirrors/git-annex
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

improve special remote docs

Browse source 
Sponsored-by: Dartmouth College's DANDI project
This commit is contained in:
Joey Hess 2024-02-05 15:48:15 -04:00
parent 083c471ee9
commit 792106abc3
No known key found for this signature in database
GPG key ID: DB12DB0FF05F8F38
3 changed files with 45 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
doc/git-annex-testremote.mdwn
View file

@ -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,

48
doc/special_remotes.mdwn
View file

@ -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.

14
doc/todo/documentation__58___improve_on_special_remotes/comment_1_edd0a4e9894d07e7bae9fef1fe4acf6d._comment Normal file
View file

@ -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 <https://git-annex.branchable.com/walkthrough/#index12h2>.
I don't know if <https://git-annex.branchable.com/special_remotes> 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.
"""]]