Copy GitHub Repository

Copy GitHub Repository is a PowerShell utility for safely publishing or copying GitHub repositories. Its default Snapshot mode is designed for clean publication: it copies the current source default-branch state into one unrelated root commit, intentionally leaving prior Git history, old branches/tags, pull requests, issues, milestones, and other historical GitHub records behind. The explicit FullHistory mode is the history-preserving alternative and keeps ordinary Git history, branches, tags, and reachable Git LFS objects.

The project prioritizes preservation, explicit human authority, verification, and recoverability. It never automatically deletes a repository or overwrites an existing destination.

Important

Snapshot execution, same-name Snapshot replacement, new-destination FullHistory execution, same-name FullHistory replacement, and supported repository-level settings restoration are implemented and live-validated. The guided repository-copy wizard is implemented and covered by the cross-platform quality gate.

Choose the right content mode

Use Snapshot when you want the repository's current default-branch contents to become a clean new repository with one fresh initial commit. Use FullHistory when commit ancestry, branches, tags, signed historical commits, blame history, or other Git-history evidence must remain intact.

For the complete user journey, support matrix, and common operating scenarios, start with the User guide.

Want to see what Snapshot automates? See Manually Creating a Clean GitHub Repository Snapshot for the equivalent Git and GitHub CLI/API procedure, including settings restoration and verification.

Safety at a glance

• Existing destination repositories are rejected rather than overwritten unless an explicit archive-and-replace flow is selected.
• Same-name replacement archives and verifies the original before the original name is reused.
• Replacement flows require exact typed confirmation; -Force cannot bypass it.
• -PlanOnly and -WhatIf are non-mutating.
• Content is verified before success is reported.
• Failures after mutation begins retain durable recovery information instead of automatically deleting or rolling back repositories.
• Version 1 supports GitHub.com only and fails closed for other hosts.

See the Product contract and Architecture for the detailed safety and verification contracts.

Prerequisites

• PowerShell 7.4 or newer
• Git
• GitHub CLI (gh)
• Git LFS when required by the selected migration mode/content

For the supported module-version line, PowerShell/platform expectations, prerequisite compatibility, deprecation, and end-of-support rules, see Support, compatibility, and deprecation policy.

Authenticate GitHub CLI before discovery:

gh auth login --hostname github.com

Install

After the first stable release is published to PowerShell Gallery, the recommended normal installation path is:

Install-PSResource CopyGitHubRepo
Import-Module CopyGitHubRepo
Start-CopyGitHubRepositoryWizard

For environments using the older PowerShellGet commands, the compatible alternative is:

Install-Module CopyGitHubRepo -Scope CurrentUser

Use PowerShell Gallery for normal public installation and updates. The repository-hosted installers remain available for bootstrap, pinned-release, development, and release-candidate scenarios where that trust model is appropriate.

To update a Gallery installation:

Update-PSResource CopyGitHubRepo

To remove a Gallery installation:

Uninstall-PSResource CopyGitHubRepo

No stable GitHub Release has been published yet, and no stable Gallery package has been published yet. Until v0.1.0 is actually released, use the prerelease workflow below for deliberate development or release-candidate testing.

Install the current prerelease build

Install the current main build with:

irm https://raw.githubusercontent.com/infoconex/copy-github-repo/main/install-prerelease.ps1 | iex
Import-Module CopyGitHubRepo -Force
Start-CopyGitHubRepositoryWizard

The prerelease bootstrap resolves main to an exact commit SHA before downloading the source archive. It does not provide the stable release checksum contract and does not publish to PowerShell Gallery.

Repository-hosted stable installation

After a stable GitHub Release exists, the repository-hosted stable convenience bootstrap remains available as an alternative to PSGallery. It resolves the latest stable release (or an explicitly requested version), verifies the release ZIP against its published SHA-256 file, and invokes the packaged installer:

irm https://raw.githubusercontent.com/infoconex/copy-github-repo/main/install-release.ps1 | iex
Import-Module CopyGitHubRepo
Start-CopyGitHubRepositoryWizard

Important

The stable convenience command downloads install-release.ps1 from mutable main and executes it before a release checksum can be verified. The bootstrap is therefore part of the trust boundary. SHA-256 protects the downloaded release ZIP against a mismatched checksum but does not independently authenticate the publisher.

For pinned-release installation, checksum limitations, -Force replacement behavior, and the complete trust model, see Installation security. The planned initial stable release is v0.1.0; those stable procedures become usable only after that release is actually published.

Uninstall

For a module installed from PowerShell Gallery, prefer the package manager that installed it:

Uninstall-PSResource CopyGitHubRepo

The project also provides its own safe interactive uninstaller for repository-hosted installations and explicit local cleanup. It discovers installed CopyGitHubRepo versions, shows the exact local paths that would be removed, and requires confirmation before deletion:

irm https://raw.githubusercontent.com/infoconex/copy-github-repo/main/uninstall.ps1 | iex

If multiple versions are installed, the script lets you remove one version, remove all validated versions, or cancel. Destructive confirmation defaults to No.

For deterministic local or automated removal, use the packaged/repository script directly:

./uninstall.ps1 -Version 0.1.0
./uninstall.ps1 -AllVersions
./uninstall.ps1 -Version 0.1.0 -DestinationRoot D:\PowerShell\Modules
./uninstall.ps1 -Version 0.1.0 -WhatIf
./uninstall.ps1 -Version 0.1.0 -Confirm:$false

-Version and -AllVersions are mutually exclusive. The uninstaller validates module identity and path containment before recursive deletion, does not remove neighboring modules, and does not require network access when run locally. The one-line command above executes mutable main, so it has the same bootstrap trust-boundary consideration as the convenience installers. See Installation security for details.

Guided quick start

The recommended human-facing entry point is the guided wizard:

Start-CopyGitHubRepositoryWizard

It discovers repositories, defaults to Snapshot/source visibility/settings restoration, lets you navigate Back/Next/Cancel before execution, displays a real Copy-GitHubRepository -PlanOnly plan, and requires an explicit Execute decision before mutation.

A repository checkout can start the same guided experience through the root launcher:

./copy-github-repo.ps1

See the User guide for scenario selection and what gets copied, then Start-CopyGitHubRepositoryWizard for complete command-level reference.

Scripted quick start

Copy-GitHubRepository is the deterministic API for scripts and automation. Preview first:

Copy-GitHubRepository `
    -SourceRepository infoconex/source `
    -DestinationRepository infoconex/destination `
    -PlanOnly

Then execute the reviewed default clean Snapshot publication:

Copy-GitHubRepository `
    -SourceRepository infoconex/source `
    -DestinationRepository infoconex/destination

FullHistory, visibility changes, replacement modes, reporting, non-interactive execution, settings choices, and all parameter details are documented in Copy-GitHubRepository.

Commands

Command	Purpose	Mutates GitHub?
Start-CopyGitHubRepositoryWizard	Guided clean-publication/history-copy workflow	Yes, after plan review and confirmation
Copy-GitHubRepository	Scriptable planning and repository publication/copy	Yes, except -PlanOnly/-WhatIf
Get-GitHubRepository	Repository discovery and metadata	No
Test-GitHubRepositoryMigration	Snapshot/FullHistory verification	No

Start with the command reference index for detailed syntax, parameter tables, outputs, failure conditions, and examples.

Documentation

Documentation uses progressive disclosure and one authoritative home per contract where practical. Start at the documentation index. See the Documentation strategy for the seven primary audiences, their journeys, the authority map, and anti-duplication rules.

Goal	Start here
Use the product safely	User guide, Installation security, Command reference
Understand product journeys, capabilities, use cases, and behavior scenarios	Product journeys and behavioral model
Understand normative product behavior and safety	Product contract, Architecture
Understand the guided interaction	Wizard contract
Understand how Snapshot can be done manually	Manual Snapshot procedure
Determine supported versions, platforms, prerequisites, and deprecation rules	Support, compatibility, and deprecation policy
Contribute or maintain the project	CONTRIBUTING.md, Engineering principles, PowerShell style guide, Source documentation
Understand versioning and publication	Versioning, PowerShell Gallery publishing
Review project security and governance	Software assurance review, SECURITY.md, Installation security, License
Understand how documentation is governed	Documentation strategy

Development

Install development dependencies as needed, then run the repository quality gate:

./build/Test-Project.ps1

The quality gate runs in GitHub Actions on Windows, Ubuntu, and macOS for pushes to main and pull requests targeting main. Controlled live-validation harnesses live under tests/e2e/; build/release tooling remains under build/.

Release publication is tag-only. A stable release tag must exactly match v<ModuleVersion> and the exact tagged commit must pass the cross-platform quality gate before publication. The release workflow validates a clean Gallery package, rejects duplicate PSGallery and GitHub Release versions, publishes with Publish-PSResource, and creates the immutable GitHub release assets. Merging to main does not publish a release.

Maintainer setup, API-key rotation, manual fallback, signing policy, and prerelease behavior are documented in Publishing to PowerShell Gallery.

See CONTRIBUTING.md for contributor guidance.

License

This project is available under the MIT License.