Skip to content

Commit 9883d63

Browse files
sdwheelersdwheeler
authored
Fixes #4874 - Add Note About Case Sensitivity (#4875)
* Fixes #4874 - Add Note About Case Sensitivity * fix switchparameters * feedback * more backticks * fix italics
1 parent 0cb73ac commit 9883d63

File tree

6 files changed

+489
-376
lines changed

6 files changed

+489
-376
lines changed

‎reference/3.0/Microsoft.PowerShell.Management/Rename-Item.md

Lines changed: 85 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
ms.date: 10/18/2018
2+
ms.date: 10/03/2019
33
schema: 2.0.0
44
locale: en-us
55
keywords: powershell,cmdlet
@@ -17,98 +17,114 @@ Renames an item in a PowerShell provider namespace.
1717
### ByPath (Default)
1818

1919
```
20-
Rename-Item [-Path] <String> [-NewName] <String> [-Force] [-PassThru] [-Credential <PSCredential>] [-WhatIf]
21-
[-Confirm] [-UseTransaction] [<CommonParameters>]
20+
Rename-Item [-Path] <String> [-NewName] <String> [-Force] [-PassThru] [-Credential <PSCredential>]
21+
[-WhatIf] [-Confirm] [-UseTransaction] [<CommonParameters>]
2222
```
2323

2424
### ByLiteralPath
2525

2626
```
27-
Rename-Item -LiteralPath <String> [-NewName] <String> [-Force] [-PassThru] [-Credential <PSCredential>]
28-
[-WhatIf] [-Confirm] [-UseTransaction] [<CommonParameters>]
27+
Rename-Item -LiteralPath <String> [-NewName] <String> [-Force] [-PassThru]
28+
[-Credential <PSCredential>] [-WhatIf] [-Confirm] [-UseTransaction] [<CommonParameters>]
2929
```
3030

3131
## DESCRIPTION
3232

33-
The `Rename-Item` cmdlet changes the name of a specified item.
34-
This cmdlet does not affect the content of the item being renamed.
33+
The `Rename-Item` cmdlet changes the name of a specified item. This cmdlet does not affect the
34+
content of the item being renamed.
3535

36-
You cannot use `Rename-Item` to move an item, such as by specifying a path together with the new name.
37-
To move and rename an item, use the `Move-Item` cmdlet.
36+
You can't use `Rename-Item` to move an item, such as by specifying a path together with the new
37+
name. To move and rename an item, use the `Move-Item` cmdlet.
3838

3939
## EXAMPLES
4040

4141
### Example 1: Rename a file
4242

43-
This command renames the file "daily_file.txt" to "monday_file.txt".
43+
This command renames the file `daily_file.txt` to `monday_file.txt`.
4444

4545
```powershell
4646
Rename-Item -Path "c:\logfiles\daily_file.txt" -NewName "monday_file.txt"
4747
```
4848

4949
### Example 2: Rename and move an item
5050

51-
This example shows that you cannot use `Rename-Item` to both rename and move an item.
52-
Specifically, you cannot supply a path for the value of the **NewName** parameter, unless the path is identical to the path specified in the **Path** parameter.
53-
Otherwise, only a new name is permitted.
51+
You can't use `Rename-Item` to both rename and move an item. Specifically, you can't supply a path
52+
for the value of the **NewName** parameter, unless the path is identical to the path specified in
53+
the **Path** parameter. Otherwise, only a new name is permitted.
5454

55-
This command attempts to rename the "project.txt" file in the current directory to "old-project.txt" in the "D:\Archive" directory. The result is the error shown in the output.
55+
This example attempts to rename the `project.txt` file in the current directory to `old-project.txt`
56+
in the `D:\Archive` directory. The result is the error shown in the output.
5657

58+
```powershell
59+
Rename-Item -Path "project.txt" -NewName "d:\archive\old-project.txt"
5760
```
58-
PS C:\> Rename-Item -Path "project.txt" -NewName "d:\archive\old-project.txt"
5961

60-
Rename-Item : Cannot rename because the target specified represents a path or device name.
62+
```Output
63+
Rename-Item : can't rename because the target specified represents a path or device name.
6164
At line:1 char:12
6265
+ Rename-Item <<<< -path project.txt -NewName d:\archive\old-project.txt
63-
+ CategoryInfo : InvalidArgument: (:) [Rename-Item], PS> Move-Item -Path "project.txt" -Destination "d:\archive\old-project.txt"
66+
+ CategoryInfo : InvalidArgument: (:) [Rename-Item], PS> Move-Item -Path "project.txt" -De
67+
stination "d:\archive\old-project.txt"
6468
```
6569

6670
### Example 3: Rename a registry key
6771

68-
This command renames a registry key from "Advertising" to "Marketing".
69-
When the command is complete, the key is renamed, but the registry entries in the key are unchanged.
72+
This example renames a registry key from **Advertising** to **Marketing**. When the command is complete,
73+
the key is renamed, but the registry entries in the key are unchanged.
7074

7175
```powershell
7276
Rename-Item -Path "HKLM:\Software\MyCompany\Advertising" -NewName "Marketing"
7377
```
7478

7579
### Example 4: Rename multiple files
7680

77-
This example shows how to use the **Replace** operator to rename multiple files, even though the **NewName** parameter does not accept wildcard characters.
81+
This example renames all the `*.txt` files in the current directory to `*.log`.
7882

79-
This command renames all of the ".txt" files in the current directory to ".log".
80-
81-
The command uses the `Get-ChildItem` cmdlet to get all of the files in the current folder that have a .txt file name extension.
82-
Then, it uses the pipeline operator (`|`) to send those files to `Rename-Item`.
83+
```powershell
84+
Get-ChildItem *.txt
85+
```
8386

84-
The value of **NewName** is a script block that runs before the value is submitted to the **NewName** parameter.
87+
```Output
88+
Directory: C:\temp\files
8589
86-
In the script block, the `$_` automatic variable represents each file object as it comes to the command through the pipeline.
87-
The command uses the dot format ('.') to get the **Name** property of each file object.
88-
The **Replace** operator replaces the ".txt" file name extension of each file with ".log".
90+
Mode LastWriteTime Length Name
91+
---- ------------- ------ ----
92+
-a---- 10/3/2019 7:47 AM 2918 Friday.TXT
93+
-a---- 10/3/2019 7:46 AM 2918 Monday.Txt
94+
-a---- 10/3/2019 7:47 AM 2918 Wednesday.txt
95+
```
8996

90-
Because the **Replace** operator works with regular expressions, the dot in front of "txt" is interpreted to match any character.
91-
To make sure that it matches only a dot ('.'), it is escaped with a backslash character (\\).
92-
The backslash character is not required in ".log" because it is a string, not a regular expression.
97+
```powershell
98+
Get-ChildItem *.txt | Rename-Item -NewName { $_.Name -replace '.txt','.log' }
99+
Get-ChildItem *.log
100+
```
93101

94-
To make sure that ".txt" is an extension, i.e. last part of the string representing the name, a dollar sign (`$`) is added after "\\.txt".
102+
```Output
103+
Directory: C:\temp\files
95104
96-
```powershell
97-
Get-ChildItem *.txt | Rename-Item -NewName { $_.name -Replace '\.txt$','.log' }
105+
Mode LastWriteTime Length Name
106+
---- ------------- ------ ----
107+
-a---- 10/3/2019 7:47 AM 2918 Friday.log
108+
-a---- 10/3/2019 7:46 AM 2918 Monday.log
109+
-a---- 10/3/2019 7:47 AM 2918 Wednesday.log
98110
```
99111

100-
## PARAMETERS
112+
The `Get-ChildItem` cmdlet gets all the files in the current folder that have a `.txt` file
113+
extension then pipes them to `Rename-Item`. The value of **NewName** is a script block that runs
114+
before the value is submitted to the **NewName** parameter.
101115

102-
### -Credential
116+
In the script block, the `$_` automatic variable represents each file object as it comes to the
117+
command through the pipeline. The script block uses the `-replace` operator to replace the file
118+
extension of each file with `.log`. Notice that matching using the `-replace` operator is not case
119+
sensitive.
103120

104-
Specifies a user account that has permission to perform this action.
105-
The default is the current user.
121+
## PARAMETERS
106122

107-
Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet.
108-
If you type a user name, you are prompted for a password.
123+
### -Credential
109124

110-
> [!WARNING]
111-
> This parameter is not supported by any providers installed with Windows PowerShell.
125+
> [!NOTE]
126+
> This parameter is not supported by any providers installed with PowerShell. To impersonate another
127+
> user, or elevate your credentials when running this cmdlet, use [Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md).
112128
113129
```yaml
114130
Type: PSCredential
@@ -124,12 +140,11 @@ Accept wildcard characters: False
124140
125141
### -Force
126142
127-
Forces the cmdlet to rename items that cannot otherwise be changed, such as hidden or read-only files or read-only aliases or variables.
128-
The cmdlet cannot change constant aliases or variables.
129-
Implementation varies from provider to provider.
130-
For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md).
143+
Forces the cmdlet to rename items that can't otherwise be changed, such as hidden or read-only files
144+
or read-only aliases or variables. The cmdlet can't change constant aliases or variables.
145+
Implementation varies from provider to provider. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md).
131146
132-
Even using the **Force** parameter, the cmdlet cannot override security restrictions.
147+
Even using the **Force** parameter, the cmdlet can't override security restrictions.
133148
134149
```yaml
135150
Type: SwitchParameter
@@ -145,11 +160,12 @@ Accept wildcard characters: False
145160
146161
### -LiteralPath
147162
148-
Specifies the path of the item to rename.
149-
Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed.
150-
No characters are interpreted as wildcards.
151-
If the path includes escape characters, enclose it in single quotation marks.
152-
Single quotation marks tell PowerShell not to interpret any characters as escape sequences.
163+
Specifies a path to one or more locations. The value of **LiteralPath** is used exactly as it is
164+
typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose
165+
it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters
166+
as escape sequences.
167+
168+
For more information, see [about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md).
153169
154170
```yaml
155171
Type: String
@@ -165,31 +181,30 @@ Accept wildcard characters: False
165181
166182
### -NewName
167183
168-
Specifies the new name of the item.
169-
Enter only a name, not a path and name.
170-
If you enter a path that differs from the path that is specified in the *Path* parameter, `Rename-Item` generates an error.
184+
Specifies the new name of the item. Enter only a name, not a path and name. If you enter a path that
185+
differs from the path that is specified in the **Path** parameter, `Rename-Item` generates an error.
171186
To rename and move an item, use `Move-Item`.
172187

173-
You cannot use wildcard characters in the value of the *NewName* parameter.
174-
To specify a name for multiple files, use the **Replace** operator in a regular expression.
175-
For more information about the Replace operator, see [about_Comparison_Operators](../Microsoft.PowerShell.Core/About/about_Comparison_Operators.md).
188+
You can't use wildcard characters in the value of the **NewName** parameter. To specify a name for
189+
multiple files, use the **Replace** operator in a regular expression. For more information about the
190+
Replace operator, see [about_Comparison_Operators](../Microsoft.PowerShell.Core/About/about_Comparison_Operators.md).
176191

177192
```yaml
178193
Type: String
179194
Parameter Sets: (All)
180195
Aliases:
181196
182197
Required: True
183-
Position: 2
198+
Position: 1
184199
Default value: None
185200
Accept pipeline input: True (ByPropertyName)
186201
Accept wildcard characters: False
187202
```
188203

189204
### -PassThru
190205

191-
Returns an object that represents the item to the pipeline.
192-
By default, this cmdlet does not generate any output.
206+
Returns an object that represents the item to the pipeline. By default, this cmdlet does not
207+
generate any output.
193208

194209
```yaml
195210
Type: SwitchParameter
@@ -198,7 +213,7 @@ Aliases:
198213
199214
Required: False
200215
Position: Named
201-
Default value: None
216+
Default value: False
202217
Accept pipeline input: False
203218
Accept wildcard characters: False
204219
```
@@ -213,7 +228,7 @@ Parameter Sets: ByPath
213228
Aliases:
214229
215230
Required: True
216-
Position: 1
231+
Position: 0
217232
Default value: None
218233
Accept pipeline input: True (ByPropertyName, ByValue)
219234
Accept wildcard characters: False
@@ -272,7 +287,9 @@ Accept wildcard characters: False
272287

273288
### CommonParameters
274289

275-
This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md).
290+
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
291+
-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,
292+
-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md).
276293

277294
## INPUTS
278295

@@ -284,12 +301,13 @@ You can pipe a string that contains a path to this cmdlet.
284301

285302
### None or an object that represents the renamed item.
286303

287-
This cmdlet generates an object that represents the renamed item, if you specify the *PassThru* parameter.
288-
Otherwise, this cmdlet does not generate any output.
304+
This cmdlet generates an object that represents the renamed item, if you specify the **PassThru**
305+
parameter. Otherwise, this cmdlet does not generate any output.
289306

290307
## NOTES
291308

292-
`Rename-Item` is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PsProvider`. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md).
309+
`Rename-Item` is designed to work with the data exposed by any provider. To list the providers
310+
available in your session, type `Get-PsProvider`. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md).
293311

294312
## RELATED LINKS
295313

0 commit comments

Comments
 (0)