Fix #4105 - explain wildcard execution (globbing)

reference/3.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md

@@ -7,7 +7,6 @@ title:  about_Command_Precedence
 # About Command Precedence
 
 ## Short description
-
 Describes how PowerShell determines which command to run.
 
 ## Long description
@@ -40,16 +39,75 @@ following rules.
   path to the script file.
 
   To run a script that is in the current directory, specify the full path, or
-  type a dot `.` to represent the current directory.
+  type a dot `.\` to represent the current directory.
 
   For example, to run the FindDocs.ps1 file in the current directory, type:
 
   ```
   .\FindDocs.ps1
   ```
 
-- If you do not specify a path, PowerShell uses the following precedence order
-  when it runs commands:
+### Using wildcards in execution
+
+You may use wildcards in command execution. Using wildcard characters is
+also known as *globbing*.
+
+PowerShell will execute a file that has a wildcard match, before a literal
+match.
+
+For example, consider a directory with the following files:
+
+```
+Get-ChildItem C:\temp\test
+
+
+    Directory: C:\temp\test
+
+
+Mode                LastWriteTime         Length Name
+----                -------------         ------ ----
+-a----        5/20/2019   2:29 PM             28 a.ps1
+-a----        5/20/2019   2:29 PM             28 [a1].ps1
+```
+
+Both script files have the same content: `$MyInvocation.MyCommand.Path`.
+This command displays the name of the script that is invoked.
+
+When you run `[a1].ps1`, the file `a.ps1` is executed even though the file
+`[a1].ps1` is a literal match.
+
+```powershell
+C:\temp\test\[a1].ps1
+```
+
+```Output
+C:\temp\test\a.ps1
+```
+
+Now lets delete the `a.ps1` file and attempt to run it again.
+
+```powershell
+Remove-Item C:\temp\test\a.ps1
+C:\temp\test\[a1].ps1
+```
+
+```Output
+C:\temp\test\[a1].ps1
+```
+
+You can see from the output that `[a1].ps1` runs this time because the literal
+match is the only file match for that wildcard pattern.
+
+For more information about how PowerShell uses wildcards, see [about_Wildcards](about_Wildcards.md).
+
+> [!NOTE]
+> To limit the search to a relative path, you must prefix the script name with
+> the relative folder name. This limits the search for commands to files in
+> that folder. Without this prefix, other PowerShell syntax may conflict and
+> there are few guarantees that the file will be found.
+
+If you do not specify a path, PowerShell uses the following precedence order
+when it runs commands:
 
   1. Alias
   2. Function

reference/4.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md

@@ -7,7 +7,6 @@ title:  about_Command_Precedence
 # About Command Precedence
 
 ## Short description
-
 Describes how PowerShell determines which command to run.
 
 ## Long description
@@ -40,16 +39,75 @@ following rules.
   path to the script file.
 
   To run a script that is in the current directory, specify the full path, or
-  type a dot `.` to represent the current directory.
+  type a dot `.\` to represent the current directory.
 
   For example, to run the FindDocs.ps1 file in the current directory, type:
 
   ```
   .\FindDocs.ps1
   ```
 
-- If you do not specify a path, PowerShell uses the following precedence order
-  when it runs commands:
+### Using wildcards in execution
+
+You may use wildcards in command execution. Using wildcard characters is
+also known as *globbing*.
+
+PowerShell will execute a file that has a wildcard match, before a literal
+match.
+
+For example, consider a directory with the following files:
+
+```
+Get-ChildItem C:\temp\test
+
+
+    Directory: C:\temp\test
+
+
+Mode                LastWriteTime         Length Name
+----                -------------         ------ ----
+-a----        5/20/2019   2:29 PM             28 a.ps1
+-a----        5/20/2019   2:29 PM             28 [a1].ps1
+```
+
+Both script files have the same content: `$MyInvocation.MyCommand.Path`.
+This command displays the name of the script that is invoked.
+
+When you run `[a1].ps1`, the file `a.ps1` is executed even though the file
+`[a1].ps1` is a literal match.
+
+```powershell
+C:\temp\test\[a1].ps1
+```
+
+```Output
+C:\temp\test\a.ps1
+```
+
+Now lets delete the `a.ps1` file and attempt to run it again.
+
+```powershell
+Remove-Item C:\temp\test\a.ps1
+C:\temp\test\[a1].ps1
+```
+
+```Output
+C:\temp\test\[a1].ps1
+```
+
+You can see from the output that `[a1].ps1` runs this time because the literal
+match is the only file match for that wildcard pattern.
+
+For more information about how PowerShell uses wildcards, see [about_Wildcards](about_Wildcards.md).
+
+> [!NOTE]
+> To limit the search to a relative path, you must prefix the script name with
+> the relative folder name. This limits the search for commands to files in
+> that folder. Without this prefix, other PowerShell syntax may conflict and
+> there are few guarantees that the file will be found.
+
+If you do not specify a path, PowerShell uses the following precedence order
+when it runs commands:
 
   1. Alias
   2. Function

reference/5.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md

@@ -7,7 +7,6 @@ title:  about_Command_Precedence
 # About Command Precedence
 
 ## Short description
-
 Describes how PowerShell determines which command to run.
 
 ## Long description
@@ -40,16 +39,75 @@ following rules.
   path to the script file.
 
   To run a script that is in the current directory, specify the full path, or
-  type a dot `.` to represent the current directory.
+  type a dot `.\` to represent the current directory.
 
   For example, to run the FindDocs.ps1 file in the current directory, type:
 
   ```
   .\FindDocs.ps1
   ```
 
-- If you do not specify a path, PowerShell uses the following precedence order
-  when it runs commands:
+### Using wildcards in execution
+
+You may use wildcards in command execution. Using wildcard characters is
+also known as *globbing*.
+
+PowerShell will execute a file that has a wildcard match, before a literal
+match.
+
+For example, consider a directory with the following files:
+
+```
+Get-ChildItem C:\temp\test
+
+
+    Directory: C:\temp\test
+
+
+Mode                LastWriteTime         Length Name
+----                -------------         ------ ----
+-a----        5/20/2019   2:29 PM             28 a.ps1
+-a----        5/20/2019   2:29 PM             28 [a1].ps1
+```
+
+Both script files have the same content: `$MyInvocation.MyCommand.Path`.
+This command displays the name of the script that is invoked.
+
+When you run `[a1].ps1`, the file `a.ps1` is executed even though the file
+`[a1].ps1` is a literal match.
+
+```powershell
+C:\temp\test\[a1].ps1
+```
+
+```Output
+C:\temp\test\a.ps1
+```
+
+Now lets delete the `a.ps1` file and attempt to run it again.
+
+```powershell
+Remove-Item C:\temp\test\a.ps1
+C:\temp\test\[a1].ps1
+```
+
+```Output
+C:\temp\test\[a1].ps1
+```
+
+You can see from the output that `[a1].ps1` runs this time because the literal
+match is the only file match for that wildcard pattern.
+
+For more information about how PowerShell uses wildcards, see [about_Wildcards](about_Wildcards.md).
+
+> [!NOTE]
+> To limit the search to a relative path, you must prefix the script name with
+> the relative folder name. This limits the search for commands to files in
+> that folder. Without this prefix, other PowerShell syntax may conflict and
+> there are few guarantees that the file will be found.
+
+If you do not specify a path, PowerShell uses the following precedence order
+when it runs commands:
 
   1. Alias
   2. Function

reference/5.1/Microsoft.PowerShell.Core/About/about_Command_Precedence.md

@@ -7,7 +7,6 @@ title:  about_Command_Precedence
 # About Command Precedence
 
 ## Short description
-
 Describes how PowerShell determines which command to run.
 
 ## Long description
@@ -40,16 +39,75 @@ following rules.
   path to the script file.
 
   To run a script that is in the current directory, specify the full path, or
-  type a dot `.` to represent the current directory.
+  type a dot `.\` to represent the current directory.
 
   For example, to run the FindDocs.ps1 file in the current directory, type:
 
   ```
   .\FindDocs.ps1
   ```
 
-- If you do not specify a path, PowerShell uses the following precedence order
-  when it runs commands:
+### Using wildcards in execution
+
+You may use wildcards in command execution. Using wildcard characters is
+also known as *globbing*.
+
+PowerShell will execute a file that has a wildcard match, before a literal
+match.
+
+For example, consider a directory with the following files:
+
+```
+Get-ChildItem C:\temp\test
+
+
+    Directory: C:\temp\test
+
+
+Mode                LastWriteTime         Length Name
+----                -------------         ------ ----
+-a----        5/20/2019   2:29 PM             28 a.ps1
+-a----        5/20/2019   2:29 PM             28 [a1].ps1
+```
+
+Both script files have the same content: `$MyInvocation.MyCommand.Path`.
+This command displays the name of the script that is invoked.
+
+When you run `[a1].ps1`, the file `a.ps1` is executed even though the file
+`[a1].ps1` is a literal match.
+
+```powershell
+C:\temp\test\[a1].ps1
+```
+
+```Output
+C:\temp\test\a.ps1
+```
+
+Now lets delete the `a.ps1` file and attempt to run it again.
+
+```powershell
+Remove-Item C:\temp\test\a.ps1
+C:\temp\test\[a1].ps1
+```
+
+```Output
+C:\temp\test\[a1].ps1
+```
+
+You can see from the output that `[a1].ps1` runs this time because the literal
+match is the only file match for that wildcard pattern.
+
+For more information about how PowerShell uses wildcards, see [about_Wildcards](about_Wildcards.md).
+
+> [!NOTE]
+> To limit the search to a relative path, you must prefix the script name with
+> the relative folder name. This limits the search for commands to files in
+> that folder. Without this prefix, other PowerShell syntax may conflict and
+> there are few guarantees that the file will be found.
+
+If you do not specify a path, PowerShell uses the following precedence order
+when it runs commands:
 
   1. Alias
   2. Function