Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fixes #4189 - Rewrite all provider cmdlets for Filter/Credential clarity #4299

Merged
merged 7 commits into from
May 15, 2019
Merged

Fixes #4189 - Rewrite all provider cmdlets for Filter/Credential clarity #4299

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
c0c0725
Fixes #4189 - Rewrite all provider cmdlets for Filter/Credential clarity
bobbytreed May 14, 2019
e6f694e
Editorial Review
bobbytreed May 14, 2019
e5a5d85
Editorial Review
bobbytreed May 14, 2019
e49bea5
Editorial Review
bobbytreed May 14, 2019
ea141c4
Editorial Review
bobbytreed May 15, 2019
00901b0
Update Get-Content.md
sdwheeler May 15, 2019
fd0fa4d
Update Clear-Content.md
sdwheeler May 15, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
177 changes: 96 additions & 81 deletions reference/6/Microsoft.PowerShell.Management/Add-Content.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
ms.date: 1/28/2019
ms.date: 5/14/2019
schema: 2.0.0
locale: en-us
keywords: powershell,cmdlet
Expand Down Expand Up @@ -50,11 +50,9 @@ their file name.
Add-Content -Path .\*.txt -Exclude help* -Value 'End of file'
```

The `Add-Content` cmdlet uses the **Path** parameter to specify all .txt files in the current
directory. The **Exclude** parameter ignores file names that match the specified pattern. The
**Value** parameter specifies the text string that is written to the files.

Use [Get-Content](Get-Content.md) to display the contents of these files.
The **Path** parameter to specifies all `.txt` files in the current directory, but the **Exclude**
parameter ignores file names that match the specified pattern. The **Value** parameter specifies the
text string that is written to the files.

### Example 2: Add a date to the end of the specified files

Expand All @@ -66,45 +64,46 @@ Add-Content -Path .\DateTimeFile1.log, .\DateTimeFile2.log -Value (Get-Date) -Pa
Get-Content -Path .\DateTimeFile1.log
```

The `Add-Content` cmdlet uses the **Path** and **Value** parameters to create two new files in the
current directory. The **Value** parameter specifies the `Get-Date` cmdlet to get the date and
passes the date to `Add-Content`. The `Add-Content` cmdlet writes the date to each file. The
**PassThru** parameter passes an object that represents the date object. Because there is no other
cmdlet to receive the passed object, it is displayed in the PowerShell console. The `Get-Content`
cmdlet displays the updated file, DateTimeFile1.log.
```Output
Tuesday, May 14, 2019 8:24:27 AM
Tuesday, May 14, 2019 8:24:27 AM
5/14/2019 8:24:27 AM
```

The `Add-Content` creates two new files in the current directory. The **Value** parameter contains
the output of the `Get-Date` The **PassThru** parameter outputs the added contents to the pipeline.
Because there is no other cmdlets to receive the output, it is displayed in the PowerShell console.
The `Get-Content` cmdlet displays the updated file, `DateTimeFile1.log`.

### Example 3: Add the contents of a specified file to another file

This example gets the content from a file and appends that content into another file.
This example gets the content from a file and stores the content in a variable. The variable is
used to append the content into another file.

```powershell
Add-Content -Path .\CopyToFile.txt -Value (Get-Content -Path .\CopyFromFile.txt)
$From = Get-Content -Path .\CopyFromFile.txt
Add-Content -Path .\CopyToFile.txt -Value $From
Get-Content -Path .\CopyToFile.txt
```

The `Add-Content` cmdlet uses the **Path** parameter to specify the new file in the current
directory, CopyToFile.txt. The **Value** parameter uses the `Get-Content` cmdlet to get the
contents of the file, CopyFromFile.txt. The parentheses around the `Get-Content` cmdlet ensure that
the command finishes before the `Add-Content` command begins. The **Value** parameter is passed to
`Add-Content`. The `Add-Content` cmdlet appends the data to the CopyToFile.txt file. The
`Get-Content` cmdlet displays the updated file, CopyToFile.txt.
- The `Get-Content` cmdlet gets the contents of `CopyFromFile.txt` and stores the contents in the
`$From` variable.
- The `Add-Content` cmdlet updates the `CopyToFile.txt` file using the contents of the `$From`
variable.
- The `Get-Content` cmdlet displays CopyToFile.txt.

### Example 4: Use a variable to add the contents of a specified file to another file
### Example 4: Add the contents of a specified file to another file using the pipeline

This example gets the content from a file and stores the content in a variable. The variable is
used to append the content into another file.
This example gets the content from a file and pipes it to the `Add-Content` cmdlet.

```powershell
$From = Get-Content -Path .\CopyFromFile.txt
Add-Content -Path .\CopyToFile.txt -Value $From
Get-Content -Path .\CopyFromFile.txt | Add-Content -Path .\CopyToFile.txt
Get-Content -Path .\CopyToFile.txt
```

The `Get-Content` cmdlet gets the contents of CopyFromFile.txt and stores the contents in the
`$From` variable. The `Add-Content` cmdlet uses the **Path** parameter to specify the
CopyToFile.txt file in the current directory. The **Value** parameter uses the `$From` variable and
passes the content to `Add-Content`. The `Add-Content` cmdlet updates the CopyToFile.txt file. The
`Get-Content` cmdlet displays CopyToFile.txt.
The `Get-Content` cmdlet gets the contents of `CopyFromFile.txt`. The results are piped to the
`Add-Content` cmdlet, which updates the `CopyToFile.txt`.
The last `Get-Content` cmdlet displays `CopyToFile.txt`.

### Example 5: Create a new file and copy content

Expand All @@ -115,16 +114,16 @@ Add-Content -Path .\NewFile.txt -Value (Get-Content -Path .\CopyFromFile.txt)
Get-Content -Path .\NewFile.txt
```

The `Add-Content` cmdlet uses the **Path** and **Value** parameters to create a new file in the
current directory. The **Value** parameter uses the `Get-Content` cmdlet to get the contents of an
existing file, CopyFromFile.txt. The parentheses around the `Get-Content` cmdlet ensure that the
command finishes before the `Add-Content` command begins. The **Value** parameter passes the
content to `Add-Content` which updates the NewFile.txt file. The `Get-Content` cmdlet displays the
contents of the new file, NewFile.txt.
- The `Add-Content` cmdlet uses the **Path** and **Value** parameters to create a new file in the
current directory.
- The `Get-Content` cmdlet gets the contents of an existing file, `CopyFromFile.txt`
and passes it to the **Value** parameter. The parentheses around the `Get-Content` cmdlet ensure
that the command finishes before the `Add-Content` command begins.
- The `Get-Content` cmdlet displays the contents of the new file, `NewFile.txt`.

### Example 6: Add content to a read-only file

This command adds the value to the file even if the **IsReadOnly** file attribute is set to True.
This command adds a value to the file even if the **IsReadOnly** file attribute is set to **True**.
The steps to create a read-only file are included in the example.

```powershell
Expand All @@ -141,17 +140,32 @@ Mode LastWriteTime Length Name
-ar-- 1/28/2019 13:35 0 IsReadOnlyTextFile.txt
```

The `New-Item` cmdlet uses the **Path** and **ItemType** parameters to create the file
IsReadOnlyTextFile.txt in the current directory. The `Set-ItemProperty` cmdlet uses the **Name**
and **Value** parameters to change the file's **IsReadOnly** property to True. The `Get-ChildItem`
cmdlet shows the file is empty (0) and has the read-only attribute (`r`). The `Add-Content` cmdlet
uses the **Path** parameter to specify the file. The **Value** parameter includes the text string
to append to the file. The **Force** parameter writes the text to the read-only file. The
`Get-Content` cmdlet uses the **Path** parameter to display the file's contents.
- The `New-Item` cmdlet uses the **Path** and **ItemType** parameters to create the file
`IsReadOnlyTextFile.txt` in the current directory.
- The `Set-ItemProperty` cmdlet uses the **Name** and **Value** parameters to change the file's
**IsReadOnly** property to True.
- The `Get-ChildItem` cmdlet shows the file is empty (0) and has the read-only attribute (`r`).
- The `Add-Content` cmdlet uses the **Path** parameter to specify the file. The **Value** parameter
includes the text string to append to the file. The **Force** parameter writes the text to the
read-only file.
- The `Get-Content` cmdlet uses the **Path** parameter to display the file's contents.

To remove the read-only attribute, use the `Set-ItemProperty` command with the **Value** parameter
set to `False`.

### Example 7: Use Filters with Add-Content

You can specify a filter to the `Add-Content` cmdlet. When using filters to qualify the **Path**
parameter, you need to include a trailing asterisk (`*`) to indicate the contents of the
path.

The following command adds the word "Done" the content of all `*.txt` files in the `C:\Temp`
directory.

```powershell
Add-Content -Path C:\Temp\* -Filter *.txt -Value "Done"
```

## PARAMETERS

### -AsByteStream
Expand All @@ -176,15 +190,10 @@ Accept wildcard characters: False

### -Credential

Specifies a user account that has permission to perform this action. The default is the current
user.

Type a user name, such as **User01** or **Domain01\User01**, or enter a **PSCredential** object,
such as one generated by the `Get-Credential` cmdlet. If you type a user name, you will be prompted
for a password.

> [!WARNING]
> [!NOTE]
> This parameter is not supported by any providers installed with PowerShell.
> To impersonate another user, or elevate your credentials when running this cmdlet,
> use [Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md)

```yaml
Type: PSCredential
Expand Down Expand Up @@ -237,8 +246,11 @@ Accept wildcard characters: False

### -Exclude

Omits the specified items. The value of this parameter qualifies the **Path** parameter. Enter a
path element or pattern, such as **\*.txt**. Wildcards are permitted.
Specifies, as a string array, an item or items that this cmdlet excludes in the operation. The value
of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as
`*.txt`. Wildcard characters are permitted. The **Exclude** parameter is effective only when the
command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character
specifies the contents of the `C:\Windows` directory.

```yaml
Type: String[]
Expand All @@ -249,16 +261,16 @@ Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Accept wildcard characters: True
```

### -Filter

Specifies a filter in the provider's format or language. The value of this parameter qualifies the
**Path** parameter. The syntax of the filter, including the use of wildcards, depends on the
provider. **Filters** are more efficient than other parameters because the provider applies filters
when objects are retrieved. Otherwise, PowerShell processes filters after the objects are
retrieved.
Specifies a filter to qualify the **Path** parameter. The [FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md)
provider is the only installed PowerShell provider that supports the use of filters. You can find
the syntax for the **FileSystem** filter language in [about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md).
Filters are more efficient than other parameters, because the provider applies them when the cmdlet
gets the objects rather than having PowerShell filter the objects after they are retrieved.

```yaml
Type: String
Expand All @@ -269,7 +281,7 @@ Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Accept wildcard characters: True
```

### -Force
Expand All @@ -292,8 +304,11 @@ Accept wildcard characters: False

### -Include

Adds only the specified items. The value of this parameter qualifies the **Path** parameter. Enter
a path element or pattern, such as **\*.txt**. Wildcards are permitted.
Specifies, as a string array, an item or items that this cmdlet includes in the operation. The value
of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as
`"*.txt"`. Wildcard characters are permitted. The **Include** parameter is effective only when the
command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character
specifies the contents of the `C:\Windows` directory.

```yaml
Type: String[]
Expand All @@ -304,15 +319,17 @@ Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Accept wildcard characters: True
```

### -LiteralPath
bobbytreed marked this conversation as resolved.
Show resolved Hide resolved

Specifies the path to the items that receive the additional content. Unlike **Path**, the value of
**LiteralPath** is used exactly as it is typed. No characters are interpreted as wildcards. If the
path includes escape characters, enclose it in single quotation marks. Single quotation marks tell
PowerShell not to interpret any characters as escape sequences.
Specifies a path to one or more locations. The value of **LiteralPath** is used exactly as it is
typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose
it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters
as escape sequences.

For more information, see [about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md).

```yaml
Type: String[]
Expand Down Expand Up @@ -464,7 +481,7 @@ Accept wildcard characters: False
This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`,
`-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`,
`-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see
[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md).

## INPUTS

Expand All @@ -481,17 +498,15 @@ represents the content. Otherwise, this cmdlet does not generate any output.

## NOTES

When you pipe an object to `Add-Content`, the object is converted to a string before it is added to
the item. The object type determines the string format, but the format might be different than the
default display of the object. To control the string format, use the formatting parameters of the
sending cmdlet.

You can also refer to `Add-Content` by its built-in alias, `ac`. For more information, see
[about_Aliases](../Microsoft.PowerShell.Core/About/about_Aliases.md).

The `Add-Content` cmdlet 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).
- When you pipe an object to `Add-Content`, the object is converted to a string before it is added to
the item. The object type determines the string format, but the format might be different than the
default display of the object. To control the string format, use the formatting parameters of the
sending cmdlet.
- You can also refer to `Add-Content` by its built-in alias, `ac`. For more information, see
[about_Aliases](../Microsoft.PowerShell.Core/About/about_Aliases.md).
- The `Add-Content` cmdlet 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).

## RELATED LINKS

Expand All @@ -507,4 +522,4 @@ providers available in your session, type `Get-PSProvider`. For more information

[New-Item](New-Item.md)

[Set-Content](Set-Content.md)
[Set-Content](Set-Content.md)
Loading