Skip to content

Commit

Permalink
cmdline/differences.md: split into a separate section from cmdline.md
Browse files Browse the repository at this point in the history
Closes #306
  • Loading branch information
bagder committed Aug 1, 2023
1 parent 970629e commit 28ef645
Show file tree
Hide file tree
Showing 3 changed files with 41 additions and 39 deletions.
1 change: 1 addition & 0 deletions SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@
* [TLS libraries](build/tls.md)
* [BoringSSL](build/boringssl.md)
* [Command line basics](cmdline.md)
* [Differences](cmdline/differences.md)
* [Command line options](cmdline/options.md)
* [Options depend on version](cmdline/versions.md)
* [URLs](cmdline/urls.md)
Expand Down
39 changes: 0 additions & 39 deletions cmdline.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,45 +3,6 @@
curl started out as a command-line tool and it has been invoked from shell
prompts and from within scripts by countless users over the years.

## Binaries and different platforms

The command-line tool `curl` is a *binary executable file*. The curl project
does not by itself distribute or provide binaries. Binary files are highly
system specific and oftentimes also bound to specific system versions.

Different curl versions, built by different people on different platforms
using different third party libraries with different built-time options make
the tool to offer different features in different places. In addition, curl is
continuously developed, so newer versions of the tool are likely to have more
and better features than the older ones.

## Command lines, quotes and aliases

There are many different command lines, shells and prompts in which curl can
be used. They all come with their own sets of limitations, rules and
guidelines to follow. The curl tool is designed to work with any of them
without causing troubles but there may be times when your specific command
line system does not match what others use or what is otherwise documented.

One way that command-line systems differ, for example, is how you can put
quotes around arguments such as to embed spaces or special symbols. In
most Unix-like shells you use double quotes (") and single quotes (')
depending if you want to allow variable expansions or not within the quoted
string, but on Windows there is no support for the single quote version.

In some environments, like PowerShell on Windows, the authors of the command
line system decided they know better and "help" the user to use another tool
instead of curl when `curl` is typed, by providing an alias that takes
precedence when a command line is executed. In order to use curl properly with
PowerShell, you need to type in its full name including the extension:
"curl.exe".

Different command-line environments will also have different maximum command
line lengths and force the users to limit how large amount of data that can be
put into a single line. curl adapts to this by offering a way to provide
command-line options through a file—or from stdin—using the [-K
option](cmdline/configfile.md).

## Garbage in gives garbage out

curl has little will of its own. It tries to please you and your wishes to a
Expand Down
40 changes: 40 additions & 0 deletions cmdline/differences.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Differences

## Binaries and different platforms

The command-line tool `curl` is a *binary executable file*. The curl project
does not by itself distribute or provide binaries. Binary files are highly
system specific and oftentimes also bound to specific system versions.

Different curl versions, built by different people on different platforms
using different third party libraries with different built-time options makes
the tool offer different features in different places. In addition, curl is
continuously developed, so newer versions of the tool are likely to have more
and better features than the older ones.

## Command lines, quotes and aliases

There are many different command lines, shells and prompts in which curl can
be used. They all come with their own sets of limitations, rules and
guidelines to follow. The curl tool is designed to work with any of them
without causing troubles but there may be times when your specific command
line system does not match what others use or what is otherwise documented.

One way that command-line systems differ, for example, is how you can put
quotes around arguments such as to embed spaces or special symbols. In
most Unix-like shells you use double quotes (") and single quotes (')
depending if you want to allow variable expansions or not within the quoted
string, but on Windows there is no support for the single quote version.

In some environments, like PowerShell on Windows, the authors of the command
line system decided they know better and "help" the user to use another tool
instead of curl when `curl` is typed, by providing an alias that takes
precedence when a command line is executed. In order to use curl properly with
PowerShell, you need to type in its full name including the extension:
"curl.exe".

Different command-line environments will also have different maximum command
line lengths and force the users to limit how large amount of data that can be
put into a single line. curl adapts to this by offering a way to provide
command-line options through a file or stdin using the [-K
option](configfile.md).

0 comments on commit 28ef645

Please sign in to comment.