Artifactspublic-v0

curl

master
ply4 git calls31 ms289 KiB3 cachedprotocol v2
143 lines5.0 KiBRaw

--form

For the HTTP protocol family, emulate a filled-in form in which a user has pressed the submit button. This makes curl POST data using the Content-Type multipart/form-data according to RFC 2388.

For SMTP and IMAP protocols, this composes a multipart mail message to transmit.

This enables uploading of binary files etc. To force the 'content' part to be a file, prefix the filename with an @ sign. To get the content part from a file, prefix the filename with the symbol <. The difference between @ and < is then that @ makes a file get attached in the post as a file upload, while the < makes a text field and gets the contents for that text field from a file.

Read content from stdin instead of a file by using a single "-" as filename. This goes for both @ and < constructs. When stdin is used, the contents is buffered in memory first by curl to determine its size and allow a possible resend. Defining a part's data from a named non-regular file (such as a named pipe or similar) is not subject to buffering and is instead read at transmission time; since the full size is unknown before the transfer starts, such data is sent as chunks by HTTP and rejected by IMAP.

Example: send an image to an HTTP server, where 'profile' is the name of the form-field to which the file portrait.jpg is the input:

curl -F profile=@portrait.jpg https://example.com/upload.cgi

Example: send your name and shoe size in two text fields to the server:

curl -F name=John -F shoesize=11 https://example.com/

Example: send your essay in a text field to the server. Send it as a plain text field, but get the contents for it from a local file:

curl -F "story=<hugefile.txt" https://example.com/

You can also instruct curl what Content-Type to use by using type=, in a manner similar to:

curl -F "web=@index.html;type=text/html" example.com

or

curl -F "name=daniel;type=text/foo" example.com

You can also explicitly change the name field of a file upload part by setting filename=, like this:

curl -F "file=@localfile;filename=nameinpost" example.com

If filename/path contains ',' or ';', it must be quoted by double-quotes like:

curl -F "file=@\"local,file\";filename=\"name;in;post\"" \
    https://example.com

or

curl -F 'file=@"local,file";filename="name;in;post"' \
    https://example.com

Note that if a filename/path is quoted by double-quotes, any double-quote or backslash within the filename must be escaped by backslash.

Quoting must also be applied to non-file data if it contains semicolons, leading/trailing spaces or leading double quotes:

curl -F 'colors="red; green; blue";type=text/x-myapp' \
   https://example.com

You can add custom headers to the field by setting headers=, like

curl -F "submit=OK;headers=\"X-submit-type: OK\"" example.com

or

curl -F "submit=OK;headers=@headerfile" example.com

The headers= keyword may appear more than once and above notes about quoting apply. When headers are read from a file, empty lines and lines starting with '#' are ignored; each header can be folded by splitting between two words and starting the continuation line with a space; embedded carriage-returns and trailing spaces are stripped. Here is an example of a header file contents:

# This file contains two headers.
X-header-1: this is a header

# The following header is folded.
X-header-2: this is
 another header

To support sending multipart mail messages, the syntax is extended as follows:

  • name can be omitted: the equal sign is the first character of the argument,

  • if data starts with '(', this signals to start a new multipart: it can be followed by a content type specification.

  • a multipart can be terminated with a '=)' argument.

Example: the following command sends an SMTP mime email consisting in an inline part in two alternative formats: plain text and HTML. It attaches a text file:

curl -F '=(;type=multipart/alternative' \
     -F '=plain text message' \
     -F '= <body>HTML message</body>;type=text/html' \
     -F '=)' -F '=@textfile.txt' ... smtp://example.com

Data can be encoded for transfer using encoder=. Available encodings are binary and 8bit that do nothing else than adding the corresponding Content-Transfer-Encoding header, 7bit that only rejects 8-bit characters with a transfer error, quoted-printable and base64 that encodes data according to the corresponding schemes, limiting lines length to 76 characters.

Example: send multipart mail with a quoted-printable text message and a base64 attached file:

curl -F '=text message;encoder=quoted-printable' \
     -F '=@localfile;encoder=base64' ... smtp://example.com
1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Long: form
5Short: F
6Arg: <name=content>
7Help: Specify multipart MIME data
8Protocols: HTTP SMTP IMAP
9Mutexed: data head upload-file
10Category: http upload post imap smtp
11Added: 5.0
12Multi: append
13See-also:
14 - data
15 - form-string
16 - form-escape
17Example:
18 - --form "name=curl" --form "file=@loadthis" $URL
19---
21# `--form`
23For the HTTP protocol family, emulate a filled-in form in which a user has
24pressed the submit button. This makes curl POST data using the Content-Type
25multipart/form-data according to RFC 2388.
27For SMTP and IMAP protocols, this composes a multipart mail message to
28transmit.
30This enables uploading of binary files etc. To force the 'content' part to be
31a file, prefix the filename with an @ sign. To get the content part from a
32file, prefix the filename with the symbol \<. The difference between @ and \<
33is then that @ makes a file get attached in the post as a file upload, while
34the \< makes a text field and gets the contents for that text field from a
35file.
37Read content from stdin instead of a file by using a single "-" as filename.
38This goes for both @ and \< constructs. When stdin is used, the contents is
39buffered in memory first by curl to determine its size and allow a possible
40resend. Defining a part's data from a named non-regular file (such as a named
41pipe or similar) is not subject to buffering and is instead read at
42transmission time; since the full size is unknown before the transfer starts,
43such data is sent as chunks by HTTP and rejected by IMAP.
45Example: send an image to an HTTP server, where 'profile' is the name of the
46form-field to which the file **portrait.jpg** is the input:
48 curl -F profile=@portrait.jpg https://example.com/upload.cgi
50Example: send your name and shoe size in two text fields to the server:
52 curl -F name=John -F shoesize=11 https://example.com/
54Example: send your essay in a text field to the server. Send it as a plain
55text field, but get the contents for it from a local file:
57 curl -F "story=<hugefile.txt" https://example.com/
59You can also instruct curl what Content-Type to use by using `type=`, in a
60manner similar to:
62 curl -F "web=@index.html;type=text/html" example.com
64or
66 curl -F "name=daniel;type=text/foo" example.com
68You can also explicitly change the name field of a file upload part by setting
69filename=, like this:
71 curl -F "file=@localfile;filename=nameinpost" example.com
73If filename/path contains ',' or ';', it must be quoted by double-quotes like:
75 curl -F "file=@\"local,file\";filename=\"name;in;post\"" \
76 https://example.com
78or
80 curl -F 'file=@"local,file";filename="name;in;post"' \
81 https://example.com
83Note that if a filename/path is quoted by double-quotes, any double-quote
84or backslash within the filename must be escaped by backslash.
86Quoting must also be applied to non-file data if it contains semicolons,
87leading/trailing spaces or leading double quotes:
89 curl -F 'colors="red; green; blue";type=text/x-myapp' \
90 https://example.com
92You can add custom headers to the field by setting headers=, like
94 curl -F "submit=OK;headers=\"X-submit-type: OK\"" example.com
96or
98 curl -F "submit=OK;headers=@headerfile" example.com
100The headers= keyword may appear more than once and above notes about quoting
101apply. When headers are read from a file, empty lines and lines starting
102with '#' are ignored; each header can be folded by splitting
103between two words and starting the continuation line with a space; embedded
104carriage-returns and trailing spaces are stripped.
105Here is an example of a header file contents:
107 # This file contains two headers.
108 X-header-1: this is a header
110 # The following header is folded.
111 X-header-2: this is
112 another header
114To support sending multipart mail messages, the syntax is extended as follows:
116- name can be omitted: the equal sign is the first character of the argument,
118- if data starts with '(', this signals to start a new multipart: it can be
119followed by a content type specification.
121- a multipart can be terminated with a '=)' argument.
123Example: the following command sends an SMTP mime email consisting in an
124inline part in two alternative formats: plain text and HTML. It attaches a
125text file:
127 curl -F '=(;type=multipart/alternative' \
128 -F '=plain text message' \
129 -F '= <body>HTML message</body>;type=text/html' \
130 -F '=)' -F '=@textfile.txt' ... smtp://example.com
132Data can be encoded for transfer using encoder=. Available encodings are
133*binary* and *8bit* that do nothing else than adding the corresponding
134Content-Transfer-Encoding header, *7bit* that only rejects 8-bit characters
135with a transfer error, *quoted-printable* and *base64* that encodes data
136according to the corresponding schemes, limiting lines length to 76
137characters.
139Example: send multipart mail with a quoted-printable text message and a
140base64 attached file:
142 curl -F '=text message;encoder=quoted-printable' \
143 -F '=@localfile;encoder=base64' ... smtp://example.com
Diagnostics4 git calls · 31 ms
CallStatusSizeTime031 ms
discover200152 B4 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=25
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2002.3 KiB · hit25 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=2321
git.response.cache=HIT
git.response.duration_ms=25
git.fetch.wants=87b019604fc70a06faa6157e91c3db0ba6caae20
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2321
git.pkt.payload.max=2300
git.sideband.band1.bytes=2299
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e2f59748113a24
Request
3d247ce5…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format