Get-ChildItem IncludeRoot Parameter

[JohnLBevan]

---

RFC:
Author: John Bevan
Status: Draft
SupercededBy:
Version:
Area: Standard Functions
Comments Due:
Plan to implement:

Get-ChildItem; Add IncludeRoot Switch

Suggestion: Currently if you wish to fetch an item and its children you have to make a call to Get-Item and Get-ChildItem. Since this is a common use case, it would be good to reduce this to a single call. By adding an IncludeRoot switch to Get-ChildItem we could easily have it fulfill this requirement.

Here are some examples of people who've hit this scenario & tried to get creative in resolving it.

Motivation

As a PowerShell user,
I can retrieve an item and its children,
so that I have the full tree returned in a single result set.

User Experience

Example of user experience with example code/script.
Include example of input and output.

Get-ChildItem -Path 'c:\demo' -IncludeRoot -Recurse | Select-Object -ExpandProperty FullName

c:\demo
c:\demo\subfolder
c:\demo\subfolder\one.txt
c:\demo\subfolder\two.txt

Specification

Include [Parameter()][Switch]$IncludeRoot in the list of available parameters.

Alternate Proposals and Considerations

The current workaround is to make separate calls to Get-Item and Get-ChildItem.

[WithHolm]

Doesn't this defeat the point of the command?
I mean you want to get the childitems of said path, not the path-item itself.

In what use cases would you use this added parameter?

[JohnLBevan]

Doesn't this defeat the point of the command?

I understand your point; that the name of the command uses the world "Child". However I wouldn't use the phrase "defeats the point" as this doesn't impact the current functionality; and there's not an existing way (with a single command) to get a folder and its decedents. Rather I'd say it adds flexibility.

Perhaps adding a -IncludeDecendents switch to the Get-Item cmdlet would be more appropriate based on the function names? To me that feels less intuitive; but either option would be welcome.

In what use cases would you use this added parameter?

In most cases where I'd call GetChildItem -Path $Path -Recurse where I'm interested in folders rather than solely files, there's a 50:50 on whether or not I'd also want to include the parent... Most times I want $Path; GetChildItem -Path $Path -Recurse | % FullName though sometimes I want Get-Item -Path $Path; GetChildItem -Path $Path -Recurse.

A couple of examples I can think of when this would be useful are:

• Looping through folders to report on or amend permissions
• Comparing folder structures of 2 directories

.. but really most cases where you'd be interested in the folders of Get-ChildItem there's likely a case where the parent may be of equal interest to its content.