Repository Commands

Overview

Repository commands provide core functionality for initializing, managing, and synchronizing git repositories across your cpm infrastructure. These commands handle bare repository creation, listing, transfer operations (push/pull), and branch merging.

Table of Contents

cpm init

Description

Initialize a new bare git repository and register it in the cpm database. This command creates a bare repository suitable for centralized management and registers all metadata for tracking and access control.

Syntax

cpm init <repository-name> [flags]

Arguments

Argument Required Description
repository-name Yes Name of the repository to create (without .git extension)

Flags

Flag Type Default Description
--path <directory> string $DATA_DIR/repos Directory path to create repository in
--org <name> string - Organization name to associate repository with

Behavior

  1. Validates repository name does not contain invalid characters
  2. Checks if repository already exists at target path
  3. Creates bare git repository using git init --bare
  4. Sets appropriate permissions (755 for directories, 644 for files)
  5. Registers repository in database with metadata
  6. If --org specified, associates repository with organization
  7. Creates initial configuration in repository

Examples

Basic Repository Initialization

# Create repository in default location
cpm init myproject

# Output:
# Repository 'myproject' initialized at /home/user/.cpm/data/repos/myproject.git
# Repository registered in database (ID: 1)

Custom Path

# Create repository in custom location
cpm init myproject --path /var/cpm/repos

# Output:
# Repository 'myproject' initialized at /var/cpm/repos/myproject.git
# Repository registered in database (ID: 2)

With Organization

# Create repository associated with organization
cpm init webapp --org engineering

# Output:
# Repository 'webapp' initialized at /home/user/.cpm/data/repos/webapp.git
# Repository registered in database (ID: 3)
# Repository associated with organization 'engineering'

Database Effects

The init command creates a record in the repositories table:

INSERT INTO repositories (name, org_id, path, created_at)
VALUES ('myproject', 1, '/path/to/myproject.git', CURRENT_TIMESTAMP);

Common Errors

Error Cause Solution
repository already exists Repository with same name exists at path Choose different name or path
organization not found Specified organization doesn't exist Create organization first with cpm org create
permission denied Insufficient permissions for target directory Check directory permissions or use sudo
invalid repository name Name contains invalid characters Use alphanumeric characters, hyphens, underscores only

cpm list

Description

List git repositories from local filesystem, remote server, or organization context. Provides flexible filtering and display options for repository discovery.

Syntax

cpm list [flags]

Flags

Flag Type Description
--local boolean List local repositories (default)
--remote <host> string List repositories on remote server (format: user@host)
--org <name> string List repositories in organization

Behavior

Local Mode (default)

  1. Scans configured data directory for .git repositories
  2. Queries database for repository metadata
  3. Displays repositories in table format with details
  4. Shows repository name, organization, path, and creation date

Remote Mode

  1. Connects to remote server via SSH
  2. Scans remote data directory for repositories
  3. Returns list of available repositories on remote
  4. Indicates which repositories exist locally

Organization Mode

  1. Queries database for organization repositories
  2. Displays only repositories associated with specified org
  3. Shows additional organization-specific metadata

Examples

List Local Repositories

cpm list
# or explicitly:
cpm list --local

# Output:
# LOCAL REPOSITORIES
#
# Name        Organization   Path                                Created
# ----------  ------------   --------------------------------    -------------------
# myproject   engineering    /home/user/.cpm/data/myproject.git 2024-01-15 10:30:00
# webapp      engineering    /home/user/.cpm/data/webapp.git    2024-01-16 14:20:00
# docs        -              /home/user/.cpm/data/docs.git      2024-01-17 09:15:00
#
# Total: 3 repositories

List Remote Repositories

cpm list --remote git@git.example.com

# Output:
# REMOTE REPOSITORIES (git@git.example.com)
#
# Name          Size    Last Modified        Available Locally
# -----------   -----   -------------------  -----------------
# myproject     24 MB   2024-01-15 10:30:00  Yes
# webapp        156 MB  2024-01-16 14:20:00  Yes
# legacy-app    89 MB   2023-12-01 08:00:00  No
# mobile-app    45 MB   2024-01-10 16:45:00  No
#
# Total: 4 repositories (2 available locally)

List Organization Repositories

cpm list --org engineering

# Output:
# ORGANIZATION REPOSITORIES (engineering)
#
# Name        Path                                Members   Created
# ----------  --------------------------------    -------   -------------------
# myproject   /home/user/.cpm/data/myproject.git 5         2024-01-15 10:30:00
# webapp      /home/user/.cpm/data/webapp.git    8         2024-01-16 14:20:00
#
# Total: 2 repositories

Output Format

The list command supports different output formats:

# Table format (default)
cpm list

# JSON format
cpm list --format json

# YAML format
cpm list --format yaml

# Simple list (names only)
cpm list --format simple

Common Errors

Error Cause Solution
connection refused Remote server not reachable Check server address and SSH connectivity
authentication failed SSH key not configured Configure SSH key with cpm ssh-key push
organization not found Specified organization doesn't exist Verify organization name with cpm org list

cpm push

Description

Push a repository to a remote server using rsync over SSH. Provides efficient incremental transfer with bandwidth optimization and progress tracking.

Syntax

cpm push <repository> [flags]

Arguments

Argument Required Description
repository Yes Name of the repository to push

Flags

Flag Type Default Description
--to <server> string main_server Target server name
--force boolean false Force push even if remote is ahead
--dry-run boolean false Show what would be transferred without actually pushing
--progress boolean false Show detailed transfer progress

Behavior

  1. Validates repository exists locally
  2. Retrieves target server configuration from database
  3. Establishes SSH connection to remote server
  4. Uses rsync for efficient incremental transfer
  5. Preserves git repository structure and permissions
  6. Updates database with sync timestamp
  7. Displays transfer summary

Transfer Protocol

cpm push uses rsync with the following options:

  • -a - Archive mode (preserves permissions, timestamps, symlinks)
  • -v - Verbose output
  • -z - Compression during transfer
  • --delete - Delete files on remote that don't exist locally
  • --progress - Show progress during transfer (if flag enabled)

Examples

Basic Push to Main Server

cpm push myproject

# Output:
# Pushing repository 'myproject' to main server...
# Connecting to git@git.example.com...
# Transferring files...
#
# Files transferred: 147
# Total size: 24.5 MB
# Transfer time: 3.2s
# Average speed: 7.6 MB/s
#
# Repository 'myproject' successfully pushed to main server

Push to Specific Server

cpm push webapp --to backup-server

# Output:
# Pushing repository 'webapp' to backup-server (backup.example.com)...
# Connecting to git@backup.example.com...
# Transferring files...
#
# Files transferred: 892
# Total size: 156.8 MB
# Transfer time: 18.4s
# Average speed: 8.5 MB/s
#
# Repository 'webapp' successfully pushed to backup-server

Dry Run

cpm push myproject --dry-run

# Output:
# DRY RUN: Would push repository 'myproject' to main server
#
# Files to transfer:
#   new: src/main.go (2.4 KB)
#   modified: README.md (5.1 KB)
#   modified: config/app.yaml (1.8 KB)
#
# Total size to transfer: 9.3 KB
#
# No files were actually transferred (dry run mode)

With Progress

cpm push webapp --progress

# Output:
# Pushing repository 'webapp' to main server...
#
#   0% [                    ] 0 B/s   ETA: --:--
#  15% [###                 ] 12.5 MB/s ETA: 00:12
#  47% [#########           ] 15.2 MB/s ETA: 00:06
#  73% [##############      ] 16.8 MB/s ETA: 00:03
# 100% [####################] 15.9 MB/s
#
# Transfer complete

Force Push

Use --force to override remote changes:

cpm push myproject --force

# Warning prompt:
# WARNING: This will overwrite changes on the remote server.
# Remote repository may have commits not present locally.
# Are you sure you want to force push? (y/N): y
#
# Force pushing repository 'myproject' to main server...
# [Transfer output...]

Common Errors

Error Cause Solution
repository not found Repository doesn't exist locally Verify name with cpm list --local
server not configured Target server not registered Add server with cpm servers add
connection timeout Server unreachable Check network connectivity and server status
permission denied SSH authentication failed Verify SSH key with cpm ssh-key push
disk full Insufficient space on remote Free up space or use different server
remote is ahead Remote has newer commits Pull first or use --force

cpm pull

Description

Pull a repository from a remote server using rsync over SSH. Efficiently synchronizes remote repository to local system with conflict detection.

Syntax

cpm pull <repository> [flags]

Arguments

Argument Required Description
repository Yes Name of the repository to pull

Flags

Flag Type Default Description
--from <server> string main_server Source server name
--force boolean false Force pull even if local has uncommitted changes
--dry-run boolean false Show what would be transferred without actually pulling
--progress boolean false Show detailed transfer progress

Behavior

  1. Validates source server configuration
  2. Checks if repository exists on remote server
  3. If repository exists locally, checks for conflicts
  4. Establishes SSH connection to remote server
  5. Uses rsync for efficient incremental transfer
  6. Updates local repository structure
  7. Registers or updates repository in database
  8. Displays transfer summary

Examples

Basic Pull from Main Server

cpm pull myproject

# Output:
# Pulling repository 'myproject' from main server...
# Connecting to git@git.example.com...
# Transferring files...
#
# Files received: 147
# Total size: 24.5 MB
# Transfer time: 2.8s
# Average speed: 8.8 MB/s
#
# Repository 'myproject' successfully pulled from main server

Pull from Specific Server

cpm pull legacy-app --from backup-server

# Output:
# Pulling repository 'legacy-app' from backup-server...
# Connecting to git@backup.example.com...
# Repository not found locally, creating new...
# Transferring files...
#
# Files received: 423
# Total size: 89.2 MB
# Transfer time: 9.6s
# Average speed: 9.3 MB/s
#
# Repository 'legacy-app' successfully pulled and registered

Pull with Progress

cpm pull webapp --progress

# Output:
# Pulling repository 'webapp' from main server...
#
#   0% [                    ] 0 B/s   ETA: --:--
#  12% [##                  ] 10.8 MB/s ETA: 00:14
#  38% [#######             ] 14.2 MB/s ETA: 00:07
#  65% [#############       ] 15.9 MB/s ETA: 00:03
# 100% [####################] 14.7 MB/s
#
# Transfer complete

Dry Run

cpm pull myproject --dry-run

# Output:
# DRY RUN: Would pull repository 'myproject' from main server
#
# Files to receive:
#   new: docs/api.md (12.3 KB)
#   modified: src/main.go (2.4 KB)
#   deleted: old/deprecated.go (1.2 KB)
#
# Total size to receive: 13.5 KB
#
# No files were actually transferred (dry run mode)

Conflict Detection

cpm detects conflicts before pulling:

cpm pull myproject

# Output:
# Pulling repository 'myproject' from main server...
# WARNING: Local repository has uncommitted changes
#
# Modified files:
#   src/config.go
#   README.md
#
# These files may be overwritten by pull.
# Recommendations:
#   1. Commit local changes first
#   2. Use --force to override local changes
#   3. Use --dry-run to see what would change
#
# Abort: Local changes detected

cpm merge

Description

Merge a source branch into a target branch within a repository. Provides automated merge with conflict detection and resolution guidance.

Syntax

cpm merge <source-branch> [flags]

Arguments

Argument Required Description
source-branch Yes Name of the branch to merge from

Flags

Flag Type Default Description
--into <branch> string current Target branch to merge into
--repo <path|name> string current directory Repository path or name
--no-ff boolean false Create merge commit even if fast-forward is possible
--squash boolean false Squash commits from source branch
--strategy <strategy> string recursive Merge strategy (recursive, ours, theirs)

Behavior

  1. Validates repository exists and is a git repository
  2. Checks current branch or switches to target branch
  3. Verifies source branch exists
  4. Checks for uncommitted changes
  5. Attempts merge using specified strategy
  6. Detects merge conflicts if any
  7. On success: commits merge and updates database
  8. On conflict: provides conflict resolution guidance

Examples

Basic Merge

# Merge feature branch into current branch
cpm merge feature-login

# Output:
# Merging 'feature-login' into 'main'...
# Analyzing branches...
#
# Fast-forward merge possible
# Updating d8f32a1..a9e4c7b
#
# Files changed: 5
#   src/auth/login.go (new)
#   src/auth/session.go (modified)
#   docs/authentication.md (new)
#   tests/auth_test.go (new)
#   go.mod (modified)
#
# Merge successful

Merge into Specific Branch

cpm merge feature-api --into develop

# Output:
# Switching to branch 'develop'...
# Merging 'feature-api' into 'develop'...
#
# Creating merge commit (no fast-forward)
# Merge commit: 3 files changed, 247 insertions(+), 12 deletions(-)
#
# Merge successful
# Branch 'develop' updated

Merge in Specific Repository

cpm merge hotfix-bug123 --into main --repo /path/to/myproject.git

# Output:
# Repository: /path/to/myproject.git
# Merging 'hotfix-bug123' into 'main'...
#
# Files changed: 2
#   src/utils/validator.go (modified)
#   tests/validator_test.go (modified)
#
# Merge successful

No Fast-Forward Merge

cpm merge feature-x --no-ff

# Output:
# Merging 'feature-x' into 'main'...
# Creating explicit merge commit...
#
# Merge commit created: a7f8e2d
# Message: Merge branch 'feature-x' into main
#
# Merge successful

Squash Merge

cpm merge feature-cleanup --squash

# Output:
# Merging 'feature-cleanup' into 'main' (squash)...
# Squashing 7 commits into one...
#
# Changes staged:
#   12 files changed, 89 insertions(+), 145 deletions(-)
#
# Please commit with appropriate message:
#   git commit -m "Feature: Code cleanup and refactoring"
#
# Squash merge prepared (not committed)

Merge Strategies

# Recursive (default) - Standard three-way merge
cpm merge feature --strategy recursive

# Ours - Resolve conflicts by keeping our version
cpm merge old-feature --strategy ours

# Theirs - Resolve conflicts by keeping their version
cpm merge external-contrib --strategy theirs

Conflict Resolution

When conflicts occur:

cpm merge feature-conflicting

# Output:
# Merging 'feature-conflicting' into 'main'...
#
# CONFLICT: Merge conflict in src/config.go
# CONFLICT: Merge conflict in README.md
#
# Automatic merge failed.
#
# Conflicted files:
#   src/config.go
#   README.md
#
# To resolve:
#   1. Edit conflicted files to resolve conflicts
#   2. Mark as resolved: git add <file>
#   3. Complete merge: git commit
#
# Or abort merge: git merge --abort
#
# Merge failed: Conflicts detected

Pre-merge Checks

# Check if merge is possible
cpm merge feature-test --dry-run

# Output:
# Dry run: Checking merge feasibility...
#
# Source branch: feature-test (15 commits ahead)
# Target branch: main (3 commits ahead)
#
# Potential conflicts: 2 files
#   src/main.go (both modified)
#   config.yaml (both modified)
#
# Recommendation: Manual merge required
# Fast-forward: Not possible

Common Errors

Error Cause Solution
branch not found Source branch doesn't exist Check branch name with git branch -a
uncommitted changes Working directory has changes Commit or stash changes first
merge conflict Conflicting changes in files Resolve conflicts manually
not a git repository Repository path invalid Verify repository with cpm list
permission denied Insufficient git permissions Check repository permissions
  • cpm init - Initialize repository
  • cpm push - Push merged repository
  • Native git commands for advanced merge operations

Best Practices

Repository Naming

  • Use lowercase with hyphens: my-project
  • Avoid special characters except hyphens and underscores
  • Keep names concise but descriptive
  • Use consistent naming convention across organization

Synchronization Workflow

  1. Initialize: cpm init project --org team
  2. Configure: Set up SSH keys and servers
  3. Push: cpm push project to backup
  4. Develop: Make changes in working repositories
  5. Sync: Regular cpm push to keep servers updated
  6. Pull: cpm pull project on other machines

Merge Strategy

  • Use --no-ff for feature branches to preserve history
  • Use --squash for cleaning up experimental branches
  • Always review changes before merging
  • Test merged code before pushing to main server

See Also