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  youtube-dl  is installed, it can be used to check for a video em‐
15       bedded in  a web page at the url, and that is added to  the  annex  in‐
16       stead.   (However,  this is disabled by default as it can be a security
17       risk.  See the documentation of annex.security.allowed-ip-addresses  in
18       git-annex(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 youtube-dl, 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              youtube-dl or a special remote, rather than the raw  content  of
53              the 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 an es‐
69              cape sequence, 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       Also the git-annex-common-options(1) can be used.
125

CAVEATS

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

SEE ALSO

133       git-annex(1)
134
135       git-annex-rmurl(1)
136
137       git-annex-registerurl(1)
138
139       git-annex-importfeed(1)
140

AUTHOR

142       Joey Hess <id@joeyh.name>
143
144                                                           git-annex-addurl(1)