tools-installer/GCM_INSTALLER_README.md

Git Credential Manager Installer

A comprehensive installer script for Git Credential Manager (GCM) that supports multiple Linux distributions and installation methods.

Features

• Version Checking: Only downloads and installs if newer version is available
• Multiple Installation Methods:
  • Package manager (apt, yum, dnf, pacman, zypper)
  • DEB packages (Debian/Ubuntu)
  • Tar.gz archives (universal)
• Cross-Platform Support: Debian, Ubuntu, RHEL, CentOS, Fedora, Arch, openSUSE
• Architecture Support: x86_64 (amd64), ARM64 (arm64), ARM (armv7l)
• Automatic Updates: Fetches latest version from GitHub releases
• Force Reinstall: Option to force reinstallation even if up-to-date

Usage

Basic Usage

# Install latest version (only if newer than current)
./install-git-credential-manager.sh

# Install specific version
./install-git-credential-manager.sh -v v2.6.0

# Force reinstall even if up-to-date
./install-git-credential-manager.sh --force

Installation Methods

# Force installation from package manager
./install-git-credential-manager.sh --package

# Force installation from DEB package
./install-git-credential-manager.sh --deb

# Force installation from tarball
./install-git-credential-manager.sh --tarball

Check Configuration Only

# Check current Git credential configuration without installing
./install-git-credential-manager.sh --checks

# Example output:
# ✓ Global credential helper: manager
# ✓ GitHub credential helper configured
# ✗ GitLab credential helper not configured
# ✗ Azure DevOps useHttpPath not configured
# ✗ Bitbucket credential helper not configured
# ✓ Gitea credential helpers configured (1 found)
#
# Run these commands to complete the configuration:
#   git config --global credential.https://gitlab.com.helper manager
#   git config --global credential.https://dev.azure.com.useHttpPath true
#   git config --global credential.https://bitbucket.org.helper manager

Help

./install-git-credential-manager.sh --help

Installation Logic

Version Checking

1. Check Current Version: Detects installed GCM version
2. Fetch Latest: Gets latest version from GitHub API
3. Compare Versions: Only proceeds if newer version available
4. Force Override: --force flag bypasses version check

Installation Priority

1. Package Manager (preferred):

   • Debian/Ubuntu: apt install git-credential-manager
   • Arch Linux: pacman -S git-credential-manager
   • Others: Falls back to manual installation

2. Distribution-Specific:

   • Debian/Ubuntu: Downloads .deb package
   • Other Linux: Downloads .tar.gz archive

3. Universal Fallback:

   • Downloads tarball for any architecture
   • Extracts and installs binary to /usr/local/bin

System Requirements

Required

• curl or wget (for downloading)
• sudo access (for system-wide installation)
• Git (for configuration)

Optional

• Package manager access (for package installations)
• Internet connection (for downloading releases)

File Locations

Installation Directory

• Binary: /usr/local/bin/git-credential-manager
• Symlink: /usr/local/bin/git-credential-manager-core
• Libraries: /usr/local/bin/lib*.so

Configuration

• Git config: ~/.gitconfig
• Credential storage: Platform-specific secure storage

Version Comparison

The installer uses semantic version comparison:

• Format: vX.Y.Z (e.g., v2.6.1)
• Logic: Compares major, minor, patch versions
• Build Info: Ignores build hashes/identifiers

Examples

# Current: v2.6.1, Latest: v2.6.1 → No update needed
# Current: v2.6.0, Latest: v2.6.1 → Update needed
# Current: v2.6.1, Latest: v2.6.0 → No update needed (newer installed)

Integration with Setup Script

The installer is automatically integrated with the main Git repository setup script:

1. Detection: Checks for existing credential managers
2. Offer Installation: Prompts to install GCM if none found
3. Configuration: Sets up Git to use the credential manager
4. Domain-Specific: Configures for specific Gitea instances

Security Features

• Official Releases: Downloads from official GitHub releases
• Checksum Verification: Can verify package integrity (future enhancement)
• Secure Storage: Uses OS keyring for credential storage
• No Plain Text: Never stores credentials in plain text

Troubleshooting

Version Detection Issues

# Check current version manually
git-credential-manager --version

# Force reinstall if version detection fails
./install-git-credential-manager.sh --force

Permission Issues

# Ensure proper permissions
sudo chown root:root /usr/local/bin/git-credential-manager
sudo chmod 755 /usr/local/bin/git-credential-manager

Network Issues

# Use specific version if network blocks GitHub API
./install-git-credential-manager.sh -v v2.6.1

Examples

Typical Workflow

# Check if update needed
./install-git-credential-manager.sh

# Output if up-to-date:
# [SUCCESS] You already have the latest version (v2.6.1)
# [SUCCESS] No installation needed. Exiting.

# Output if update available:
# [INFO] Current version: v2.6.0
# [INFO] Latest version: v2.6.1
# [INFO] Newer version available: v2.6.1 > v2.6.0
# [SUCCESS] Installation completed successfully!

Automated Installation

# Script for automated setup
#!/bin/bash
./install-git-credential-manager.sh --force --package
git config --global credential.helper manager

Post-Installation Configuration Check

After successful installation, the installer automatically checks and configures all required Git presets:

✅ Preset Verification

The installer checks these configurations:

• Global credential helper: credential.helper manager
• GitHub: credential.https://github.com.helper manager
• GitLab: credential.https://gitlab.com.helper manager
• Bitbucket: credential.https://bitbucket.org.helper manager
• Azure DevOps: credential.https://dev.azure.com.useHttpPath true
• Gitea servers: Domain-specific credential helpers

📋 Configuration Report

The installer provides:

• Status summary: Shows which presets are configured (✓) or missing (✗)
• Exact commands: Lists the exact git config commands needed
• Testing guidance: Commands to verify the configuration
• Service-specific advice: Tailored guidance for different Git hosting services

🔧 Manual Configuration

If presets are missing, the installer shows exactly what to run:

# Example output for missing presets:
Run these commands to complete the configuration:
  git config --global credential.https://gitlab.com.helper manager
  git config --global credential.https://dev.azure.com.useHttpPath true
  git config --global credential.https://bitbucket.org.helper manager
  # For Gitea servers, configure domain-specific helper:
  git config --global credential.https://go-gitea.mywire.org.helper manager

After configuring, test with:
  git config --global --list | grep credential

Integration with Setup Script

The installer integrates seamlessly with the main setup script:

• Automatically called when Git Credential Manager is needed
• Respects user preferences for installation location
• Provides clear feedback on installation strategy
• Handles both new installations and updates
• Performs comprehensive preset checking and configuration

Contributing

To add support for new distributions or architectures:

1. Update detect_os() function for new package managers
2. Add architecture detection in get_arch() function
3. Update installation methods in install_from_*() functions
4. Test with target distribution

License

This installer script follows the same license as Git Credential Manager (MIT).