1git-annex-addurl(1)         General Commands Manual        git-annex-addurl(1)
2
3
4

NAME

6       git-annex-addurl - add urls to annex
7

SYNOPSIS

9       git annex addurl [url ...]
10

DESCRIPTION

12       Downloads each url to its own file, which is added to the annex.
13
14       When  yt-dlp is installed, it can be used to check for a video embedded
15       in  a web page at the url, and that is  added  to  the  annex  instead.
16       (However,  this  is  disabled  by default as it can be a security risk.
17       See the documentation of annex.security.allowed-ip-addresses in git-an‐
18       nex(1) for details.)
19
20       Special  remotes can add other special handling of particular urls. For
21       example, the bittorrent special remotes makes  urls  to  torrent  files
22       (including  magnet  links)  download  the content of the torrent, using
23       aria2c.
24
25       Normally the filename is based on the  full  url,  so  will  look  like
26       "www.example.com_dir_subdir_bigfile".  In some cases, addurl is able to
27       come up with a better filename based on other information. Options  can
28       also be used to get better filenames.
29

OPTIONS

31       --fast
32
33              Avoid  immediately downloading the url. The url is still checked
34              (via HEAD) to verify that it exists, and to get its size if pos‐
35              sible.
36
37       --relaxed
38              Don't  immediately  download the url, and avoid storing the size
39              of the url's content. This makes git-annex accept whatever  con‐
40              tent is there at a future point.
41
42              This  is the fastest option, but it still has to access the net‐
43              work to check if the url contains embedded  media.  When  adding
44              large numbers of urls, using --relaxed --raw is much faster.
45
46       --raw  Prevent  special  handling  of  urls  by yt-dlp, bittorrent, and
47              other special remotes. This will for example, make addurl  down‐
48              load the .torrent file and not the contents it points to.
49
50       --no-raw
51              Require  content  pointed  to  by the url to be downloaded using
52              yt-dlp or a special remote, rather than the raw content  of  the
53              url. if that cannot be done, the add will fail.
54
55       --file=name
56              Use  with  a  filename that does not yet exist to add a new file
57              with the specified name and the content downloaded from the url.
58
59              If the file already exists, addurl will record that  it  can  be
60              downloaded from the specified url(s).
61
62       --preserve-filename
63              When  the  web server (or torrent, etc) provides a filename, use
64              it as-is, avoiding sanitizing unusual characters, or  truncating
65              it to length, or any other modifications.
66
67              git-annex  will  still check the filename for safety, and if the
68              filename has a security problem such as path traversal or a con‐
69              trol character, it will refuse to add it.
70
71       --pathdepth=N
72              Rather  than basing the filename on the whole url, this causes a
73              path to be constructed, starting at the specified  depth  within
74              the path of the url.
75
76              For  example,  adding  the  url  http://www.example.com/dir/sub
77              dir/bigfile with --pathdepth=1  will  use  "dir/subdir/bigfile",
78              while --pathdepth=3 will use "bigfile".
79
80              It  can  also  be negative; --pathdepth=-2 will use the last two
81              parts of the url.
82
83       --prefix=foo --suffix=bar
84              Use to adjust the filenames that are created by addurl. For  ex‐
85              ample,  --suffix=.mp3  can  be  used  to add an extension to the
86              file.
87
88       --no-check-gitignore
89              By default, gitignores are honored and it will refuse  to  down‐
90              load  an  url  to  a file that would be ignored. This makes such
91              files be added despite any ignores.
92
93       --jobs=N -JN
94              Enables parallel downloads when multiple urls are  being  added.
95              For example: -J4
96
97              Setting this to "cpus" will run one job per CPU core.
98
99       --batch
100              Enables  batch  mode,  in which lines containing urls to add are
101              read from stdin.
102
103       -z     Makes the --batch input be delimited by  nulls  instead  of  the
104              usual newlines.
105
106       --with-files
107              When  batch  mode  is enabled, makes it parse lines of the form:
108              "$url $file"
109
110              That adds the specified url to the specified  file,  downloading
111              its  content if the file does not yet exist; the same as git an‐
112              nex addurl $url --file $file
113
114       --json Enable JSON output. This is intended to be  parsed  by  programs
115              that use git-annex. Each line of output is a JSON object.
116
117       --json-progress
118              Include progress objects in JSON output.
119
120       --json-error-messages
121              Messages that would normally be output to standard error are in‐
122              cluded in the JSON instead.
123
124       --backend
125              Specifies which key-value backend to use.
126
127       Also the git-annex-common-options(1) can be used.
128

CAVEATS

130       If annex.largefiles is configured, and does not match a file, git annex
131       addurl  will add the non-large file directly to the git repository, in‐
132       stead of to the annex. However, this is not done when --fast  or  --re‐
133       laxed is used.
134

SEE ALSO

136       git-annex(1)
137
138       git-annex-rmurl(1)
139
140       git-annex-registerurl(1)
141
142       git-annex-importfeed(1)
143

AUTHOR

145       Joey Hess <id@joeyh.name>
146
147                                                           git-annex-addurl(1)
Impressum