Rename‑GitLocalBranch

SYNOPSIS

Renames a local Git branch and optionally updates remote tracking and default branch settings.

SYNTAX

Rename-GitLocalBranch [-Name] <String> [-NewName] <String> [[-RemoteName] <String>] [-SetDefault]
 [-TrackUpstream] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]

DESCRIPTION

This function renames a local Git branch. It can also update the upstream tracking and set the new branch as the default for the remote repository.

This function supports ShouldProcess functionality for safe operations and includes a Force parameter to bypass confirmation prompts.

EXAMPLES

EXAMPLE 1

Rename-GitLocalBranch -Name "feature/old-name" -NewName "feature/new-name"

This example renames a local branch from "feature/old-name" to "feature/new-name". It does not affect any remote settings.

EXAMPLE 2

Rename-GitLocalBranch -Name "develop" -NewName "main" -TrackUpstream -SetDefault

This example renames the local "develop" branch to "main", sets up upstream tracking for the new branch, and sets it as the default branch for the remote repository. This is useful when standardizing branch names across projects.

EXAMPLE 3

Rename-GitLocalBranch -Name "bugfix/issue-123" -NewName "hotfix/critical-fix" -RemoteName "upstream" -TrackUpstream

This example renames a branch from "bugfix/issue-123" to "hotfix/critical-fix", sets up tracking with a remote named "upstream", but does not change the default branch.

EXAMPLE 4

Rename-GitLocalBranch -Name "feature/old-name" -NewName "feature/new-name" -Force

This example renames a branch with the Force parameter, bypassing confirmation prompts when used with -Confirm:$false.

PARAMETERS

-Force

Forces the operation to proceed without confirmation prompts, similar to -Confirm:$false.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Name

The current name of the branch to be renamed.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-NewName

The new name for the branch.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-RemoteName

The name of the remote repository. Defaults to 'origin'.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 3
Default value: Origin
Accept pipeline input: False
Accept wildcard characters: False

-SetDefault

If specified, sets the newly renamed branch as the default branch for the remote repository.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-TrackUpstream

If specified, sets up the newly renamed branch to track the upstream branch.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

None

This function does not accept pipeline input.

OUTPUTS

None

This function does not return any output.

NOTES

This function requires Git to be installed and accessible in the system PATH.

RELATED LINKS