Using typings d.ts manager: How do you specify which source to use and why

Question

In typings the new tsd manager for typescript definitions after reading the doc's I am confused on what the different sources mean and how to install by specifying the source and version

Example if you search for foundation-sites by

typings search foundation-sites

the result is

 foundation-sites global             2016-02-11T00:39:58.000Z 1
 foundation-sites dt                 2016-03-17T12:06:54.000Z 1        http://foundation.zurb.com/

This command typings install foundation-sites --save fails.

I then added the ambient flag and it worked, but from my research both global and dt are considered ambient, although I still don't fully understand what ambient means in the context of dt being ambient and also global being ambient. See page describing source in more detail. This page lists 3 ambients in additon to the dt that we already know about

lib for shared environment functionality (ambient)

env for programming environment typings (ambient)

global for global libraries (ambient)

What do the above differences mean

If you have multiple sources as in the above search results and just use -ambient with no source specified then

1)Which one gets installed and why? The one from global dated earlier or dt dated later.

Can you provide the correct install command for choosing a source and version. Please include an example for non-ambient repo's like github versus the ambient repo's such as global and dt

2)Do both global and dt source require --ambient flag?

3)Do typings only install automatically if they are in the npm folder in the typings registry.

Example, I can install moment using typings install moment and it works. From what I can tell it works because it is listed in the npm folder in the typings registry.

Running the command as suggested by Corey typings install dt!foundation-sites

results in error bash: !foundation-sites: event not found

FIXED: Thanks to Corey -- For bash users escape with a \ example

typings install dt\!foundation-sites

Answer 1

I think ambient means it comes from DefinitelyTyped:

[ambient] includes DefinitelyTyped in the lookup

The typings docs further state:

You're possibly wondering what it's like going from using TSD to Typings. Using Typings is very similar to using TSD. Where you previously would have:

tsd install react --save You would now:

typings install react --ambient --save

And I believe DefinitelyTyped will only have on version of any definition because it does not support versioning. You need to specify which one you want using the :

typings install (with no arguments, in package directory)
typings install [<name>=]<location>

  <name>      Module name of the installed definition
  <location>  The location to read from (described below)

Valid Locations:
  [<source>!]<pkg>[@<version>][#<tag>]
  file:<path>
  github:<org>/<repo>[/<path>][#<commitish>]
  bitbucket:<org>/<repo>[/<path>][#<commitish>]
  npm:<pkg>[/<path>]
  bower:<pkg>[/<path>]
  http(s)://<host>/<path>

  <source>    The registry mirror (E.g. "npm", "bower", "env", "global", "dt", ...)
  <path>      Path to a `.d.ts` file or `typings.json`
  <host>      A domain name (with optional port)
  <version>   A semver range (E.g. ">=4.0")
  <tag>       The specific tag of a registry entry
  <commitish> A git commit, tag or branch

Options:
  [--save|-S]       Persist to "dependencies"
  [--save-dev|-D]   Persist to "devDependencies"
  [--save-peer|-P]  Persist to "peerDependencies"
  [--ambient|-A]    Install and persist as an ambient definition
    [-SA]           Persist to "ambientDependencies"
    [-DA]           Persist to "ambientDevDependencies"
  [--production]    Install only production dependencies (omits dev dependencies)

Aliases: i, in

For example,

>typings install dt!foundation-sites
typings INFO reference Stripped reference "https://raw.githubusercontent.com/DefinitelyTyped/DefinitelyTyped/7de6c3dd94feaeb21f20054b9f30d5dabc5efabd/jquery/jquery.d.ts" during installation from "foundation-sites"
foundation-sites
└── (No dependencies)

And then I get the dt version inside of typings/browser/definitions/foudation-sites.

So the answer to your question(s):

1)Which one gets installed and why? The one from global dated earlier or dt dated later.

Neither, you must specify a source

2)Do both global and dt source require --ambient flag?

No, --ambient will "Install and persist as an ambient definition"

3)Do typings only install automatically if they are in the npm folder in the typings registry.

I assume installation is "automatic" only if there are no ambiguities.