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
15       embedded in  a web page at the url, and that  is  added  to  the  annex
16       instead.  (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       --file=name
51              Use  with  a  filename that does not yet exist to add a new file
52              with the specified name and the content downloaded from the url.
53
54              If the file already exists, addurl will record that  it  can  be
55              downloaded from the specified url(s).
56
57       --preserve-filename
58              When  the  web server (or torrent, etc) provides a filename, use
59              it as-is, avoiding sanitizing unusual characters, or  truncating
60              it to length, or any other modifications.
61
62              git-annex  will  still check the filename for safety, and if the
63              filename has a security problem such as  path  traversal  or  an
64              escape sequence, it will refuse to add it.
65
66       --pathdepth=N
67              Rather  than basing the filename on the whole url, this causes a
68              path to be constructed, starting at the specified  depth  within
69              the path of the url.
70
71              For  example,  adding  the  url  http://www.example.com/dir/sub‐
72              dir/bigfile with --pathdepth=1  will  use  "dir/subdir/bigfile",
73              while --pathdepth=3 will use "bigfile".
74
75              It  can  also  be negative; --pathdepth=-2 will use the last two
76              parts of the url.
77
78       --prefix=foo --suffix=bar
79              Use to adjust the filenames that  are  created  by  addurl.  For
80              example,  --suffix=.mp3  can  be used to add an extension to the
81              file.
82
83       --no-check-gitignore
84              By default, gitignores are honored and it will refuse  to  down‐
85              load  an  url  to  a file that would be ignored. This makes such
86              files be added despite any ignores.
87
88       --jobs=N -JN
89              Enables parallel downloads when multiple urls are  being  added.
90              For example: -J4
91
92              Setting this to "cpus" will run one job per CPU core.
93
94       --batch
95              Enables  batch  mode,  in which lines containing urls to add are
96              read from stdin.
97
98       -z     Makes the --batch input be delimited by  nulls  instead  of  the
99              usual newlines.
100
101       --with-files
102              When  batch  mode  is enabled, makes it parse lines of the form:
103              "$url $file"
104
105              That adds the specified url to the specified  file,  downloading
106              its  content  if  the  file  does not yet exist; the same as git
107              annex addurl $url --file $file
108
109       --json Enable JSON output. This is intended to be  parsed  by  programs
110              that use git-annex. Each line of output is a JSON object.
111
112       --json-progress
113              Include progress objects in JSON output.
114
115       --json-error-messages
116              Messages  that  would  normally  be output to standard error are
117              included in the json instead.
118

CAVEATS

120       If annex.largefiles is configured, and does not match a file, git annex
121       addurl  will  add  the  non-large  file directly to the git repository,
122       instead of to the annex. However, this  is  not  done  when  --fast  or
123       --relaxed is used.
124

SEE ALSO

126       git-annex(1)
127
128       git-annex-rmurl(1)
129
130       git-annex-registerurl(1)
131
132       git-annex-importfeed(1)
133

AUTHOR

135       Joey Hess <id@joeyh.name>
136
137                                                           git-annex-addurl(1)