Merge pull request #16 from Microsoft/nickpape-msft-patch-2

Add missing information

pages/commands/rush_add.md

@@ -5,7 +5,7 @@ navigation_source: docs_nav
 ---
 
 ```
-usage: rush add [-h] -p PACKAGE_NAME [--exact] [--caret] [--dev] [-m] [-s]
+usage: rush add [-h] -p PACKAGE [--exact] [--caret] [--dev] [-m] [-s]
 
 Adds a specified package as a dependency of the current project (as
 determined by the current working directory) and then runs "rush update". If
@@ -19,11 +19,14 @@ dependency.
 
 Optional arguments:
   -h, --help            Show this help message and exit.
-  -p PACKAGE_NAME, --package PACKAGE_NAME
+  -p PACKAGE, --package PACKAGE
                         (Required) The name of the package which should be
-                        added as a dependency. Also, the version specifier
-                        can be appended after an "@" sign (similar to NPM's
-                        semantics).
+                        added as a dependency. A SemVer version specifier can
+                        be appended after an "@" sign. WARNING: Symbol
+                        characters are usually interpreted by your shell, so
+                        it's recommended to use quotes. For example, write
+                        "rush add --project "example@^1.2.3"" instead of
+                        "rush add --project example@^1.2.3".
   --exact               If specified, the SemVer specifier added to the
                         package.json will be an exact version (e.g. without
                         tilde or caret).

pages/developer/modifying_package_json.md

@@ -18,20 +18,29 @@ In a Rush repo, you should instead use the [rush add]({% link pages/commands/rus
 ~/my-repo$ cd apps/my-app
 
 # Add "example-lib" as a dependency of "my-app", and then automatically run "rush update":
-~/my-repo/apps/my-app$ rush add example-lib
+~/my-repo/apps/my-app$ rush add --package example-lib
 ```
 
 The `rush add` command can also be used to update the version of an existing dependency:
 
 ```sh
 # Update "my-app" to use "example-lib" version "~1.2.3":
-~/my-repo/apps/my-app$ rush add example-lib@1.2.3
+~/my-repo/apps/my-app$ rush add --package example-lib@1.2.3
 
 # Or if you want the version specifier "^1.2.3":
-~/my-repo/apps/my-app$ rush add example-lib@1.2.3 --caret
+~/my-repo/apps/my-app$ rush add --package example-lib@1.2.3 --caret
 
-# If any other projects in the repo are using "example-lib", you can update them all together:
-~/my-repo/apps/my-app$ rush add example-lib@1.2.3 --make-consistent
+# A more advanced example, where we query the NPM registry to find latest version that is
+# compatible with the SemVer specifier "^1.2.0" and then add it as a tilde dependency
+# such as "~1.5.3".
+#
+# IMPORTANT: When specifying symbol characters on the command line, use quotes so they
+# don't get misinterpreted by your shell.
+~/my-repo/apps/my-app$ rush add --package "example-lib@^1.2.0"
+
+# If any other projects in the repo are using "example-lib", you can update them all
+# to "1.2.3" in bulk:
+~/my-repo/apps/my-app$ rush add --package example-lib@1.2.3 --make-consistent
 
 ```