doc: introduce temporary environment and shared environment (#2987)

Co-authored-by: Alex Ames <[email protected]>
Co-authored-by: Ian Butterworth <[email protected]>
Co-authored-by: Kristoffer Carlsson <[email protected]>

Author: 4 people

docs/src/environments.md

@@ -4,7 +4,7 @@ The following discusses Pkg's interaction with environments. For more on the rol
 
 ## Creating your own projects
 
-So far we have added packages to the default project at `~/.julia/environments/v1.0`. It is however easy to create other, independent, projects.
+So far we have added packages to the default project at `~/.julia/environments/v1.6`. It is however easy to create other, independent, projects.
 It should be pointed out that when two projects use the same package at the same version, the content of this package is not duplicated.
 In order to create a new project, create a directory for it and then activate that directory to make it the "active project", which package operations manipulate:
 
@@ -15,32 +15,33 @@ julia> cd("MyProject")
 /Users/kristoffer/MyProject
 
 # we can now use "." instead of a longer relative or full path:
-(v1.0) pkg> activate .
+(@v1.6) pkg> activate .
+Activating new environment at `/Users/kristoffer/MyProject/Project.toml`
 
 (MyProject) pkg> st
-    Status `Project.toml`
+    Status `/Users/kristoffer/MyProject/Project.toml` (empty project)
 ```
 
 Note that the REPL prompt changed when the new project is activated. Since this is a newly created project, the status command shows that it contains no packages, and in fact, it has no project or manifest file until we add a package to it:
 
 ```julia-repl
 julia> readdir()
-0-element Array{String,1}
+String[]
 
 (MyProject) pkg> add Example
-  Updating registry at `~/.julia/registries/General`
-  Updating git-repo `https://github.com/JuliaRegistries/General.git`
- Resolving package versions...
-  Updating `Project.toml`
-  [7876af07] + Example v0.5.1
-  Updating `Manifest.toml`
-  [7876af07] + Example v0.5.1
-  [8dfed614] + Test
+  Installing known registries into `~/.julia`
+       Added registry `General` to `~/.julia/registries/General`
+   Resolving package versions...
+   Installed Example ─ v0.5.3
+    Updating `/Users/kristoffer/MyProject/Project.toml`
+  [7876af07] + Example v0.5.3
+    Updating `~/Users/kristoffer/MyProject/Manifest.toml`
+  [7876af07] + Example v0.5.3
 Precompiling project...
   1 dependency successfully precompiled in 2 seconds
 
 julia> readdir()
-2-element Array{String,1}:
+2-element Vector{String}:
  "Manifest.toml"
  "Project.toml"
 
@@ -49,18 +50,15 @@ julia> print(read("Project.toml", String))
 Example = "7876af07-990d-54b4-ab0e-23690620f79a"
 
 julia> print(read("Manifest.toml", String))
+# This file is machine-generated - editing it directly is not advised
+
 [[Example]]
-deps = ["Test"]
-git-tree-sha1 = "8eb7b4d4ca487caade9ba3e85932e28ce6d6e1f8"
+git-tree-sha1 = "46e44e869b4d90b96bd8ed1fdcf32244fddfb6cc"
 uuid = "7876af07-990d-54b4-ab0e-23690620f79a"
-version = "0.5.1"
-
-[[Test]]
-uuid = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+version = "0.5.3"
 ```
 
-This new environment is completely separate from the one we used earlier.
-
+This new environment is completely separate from the one we used earlier. See [`Project.toml` and `Manifest.toml`](@ref Project-and-Manifest) for a more detailed explanation.
 
 ## Project Precompilation
 
@@ -92,9 +90,16 @@ Precompiling project...
 Simply clone their project using e.g. `git clone`, `cd` to the project directory and call
 
 ```julia-repl
-(v1.0) pkg> activate .
+shell> git clone https://github.com/JuliaLang/Example.jl.git
+Cloning into 'Example.jl'...
+...
 
-(SomeProject) pkg> instantiate
+(@v1.6) pkg> activate Example.jl
+Activating project at `~/Example.jl`
+
+(Example) pkg> instantiate
+  No Changes to `~/Example.jl/Project.toml`
+  No Changes to `~/Example.jl/Manifest.toml`
 ```
 
 If the project contains a manifest, this will install the packages in the same state that is given by that manifest.
@@ -107,3 +112,26 @@ Otherwise, it will resolve the latest versions of the dependencies compatible wi
     ```bash
     $ julia --project=. myscript.jl
     ```
+
+
+## Temporary environments
+
+Temporary environments make it easy to start an environment from a blank slate to test a package or set of
+packages, and have Pkg automatically delete the environment when you're done.
+For instance, when writing a bug report, you may want to test your minimal reproducible
+example in a 'clean' environment to ensure it's actually reproducible as written. You might
+also want a scratch space to try out a new package, or a sandbox to resolve version conflicts
+between several incompatible packages.
+
+```julia-repl
+(@v1.6) pkg> activate --temp # requires Julia 1.5 or later
+  Activating new environment at `/var/folders/34/km3mmt5930gc4pzq1d08jvjw0000gn/T/jl_a31egx/Project.toml`
+
+(jl_a31egx) pkg> add Example
+    Updating registry at `~/.julia/registries/General`
+   Resolving package versions...
+    Updating `/private/var/folders/34/km3mmt5930gc4pzq1d08jvjw0000gn/T/jl_a31egx/Project.toml`
+  [7876af07] + Example v0.5.3
+    Updating `/private/var/folders/34/km3mmt5930gc4pzq1d08jvjw0000gn/T/jl_a31egx/Manifest.toml`
+  [7876af07] + Example v0.5.3
+```