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

tip

Browse source
This commit is contained in:
Joey Hess 2024-05-30 13:26:34 -04:00
parent 0155abfba4
commit f877afe930
No known key found for this signature in database
GPG key ID: DB12DB0FF05F8F38
2 changed files with 97 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
doc/git-remote-annex.mdwn
View file

@ -78,25 +78,6 @@ time, for one of the pushes to be overwritten by the other one. In this
situation, the overwritten push will appear to have succeeded, but pulling
later will show the true situation.
# HTTPALSO
If the content of a special remote is published via http, a httpalso
special remote can be initialized, and used to `git clone` and `git fetch`
over http.
For example, a directory special remote named "foo" is published
at `https://example.com/foo/`, set up the httpalso remote like this
to access it:
git-annex initremote foohttp --with-url --sameas=foo type=httpalso url=https://example.com/foo/
Be sure to remember to include exporttree=yes if the remote is configured
that way.
Once a httpalso remote is set up like this, `git fetch` from it to display
its full annex:: url. That url can be shared with others to let them clone
the repository.
# REPOSITORY FORMAT
The git repository is stored in the special remote using special annex objects

97
doc/tips/storing_a_git_repository_on_any_special_remote.mdwn Normal file
View file

@ -0,0 +1,97 @@
Usually a [[special remote|special_remotes]] stores the content of annexed
files, but you need another git remote to store your git repository. But now we
have [[git-remote-annex]], which lets most any special remote store a git
repository alongside the annexed files. So you can `git pull`, `git push`, and
even `git clone` from a special remote.
In order to use [[git-remote-annex]], the special remote needs to have
its url set to an url starting with "annex::".
Special remotes are not configured with such an url by default,
but it can easily be set by using the `--with-url` parameter
when running [[git-annex-initremote]] or [[git-annex-enableremote]].
Let's say you have a special remote named "foo" you want to use
with [[git-remote-annex]]. This command will configure remote.foo.url
and also remote.foo.fetch:
git-annex enableremote foo --with-url
Or you could configure it manually:
git config remote.foo.url annex::
git config remote.foo.fetch '+refs/heads/*:refs/remotes/foo/*'
Now you can `git push foo` and `git pull foo`. And commands like
`git-annex sync` will also use foo as a git repository.
You can even `git clone` from the special remote. To do that, you need
an url that tells git-annex all about the special remote's configuration.
The easy way to get that url is to run `git fetch foo`,
and look at its output, which might look like this if it's an S3 bucket.
Full remote url: annex::13c2500f-a302-4331-9720-6ec43cb8da2b?type=S3&encryption=none&bucket=foo
## does it work just like any other git remote?
Very close, but not completely the same.
If two people make conflicting pushes into a special remote at the same time,
one of the pushes will overwrite the other one. In this situation, the
overwritten push will appear to have succeeded, but pulling later will show the
true situation.
While pushes are mostly done incrementally, and so are fast, sometimes it will
do a full re-upload of the contents of your repository, which is slower.
If you `git push --delete foo badbranch`, the branch will be deleted, but
all traces of it will not be immediately removed from the special remote.
See the "REPOSITORY FORMAT" section of [[git-remote-annex]] for details.
## what special remotes does this work with?
Some types of special remotes already have an url that points at a git
repository, so it can't also be set to an annex:: url.
For example, [[special_remotes/git-lfs]].
A few other types of special remotes can't be used for other reasons,
including [[special_remotes/web]] and [[special_remotes/borg]].
Encrypted special remotes *can* be used as git remotes. But, the git repository
contains information that is needed to decrypt the files that are stored
on the special remote. This means it's not possible to clone from an encrypted
special remote. So you will be prompted to set a git config before using
[[git-remote-annex]] with an encrypted special remote, to avoid shooting
yourself in the foot.
You *can* use this with special remotes that are configured with
"exporttree=yes". (The git repository is written under `.git/annex/objects/`
on the remote to keep it separate from the exported files.)
But this won't work with special remotes that are configured with
"importrree=yes" but without "exportrree=yes".
## httpalso special remotes
If the content of a special remote gets written to some location that is
published to http, you can use the [[special_remotes/httpalso]] special
remote with [[git-remote-annex]] to `git clone` and `git fetch` over http.
For example, if your directory special remote named "foo" is published
at `https://example.com/foo/`, set up the httpalso remote like this
to access it:
git-annex initremote foohttp --with-url --sameas=foo type=httpalso url=https://example.com/foo/
Be sure to remember to include exporttree=yes if the remote is configured
that way.
Once a httpalso remote is set up like this, `git fetch` from it to display
its full annex:: url. That url can be shared with others to let them clone
the repository.
The url will be rather long and ugly. There's a way to make a shorter url
that you can tell someone to let them clone your httpalso repository.
Just write the url to a file on your website. Then wrap the url to that
file in an annex:: url, for example "annex::https://example.com/foo-repo"
Currently this only works for httpalso urls.