lg0219/github-ghclone

GitHub GHClone - Skill de Aceleração do GitHub para a China

Cenário de Uso

Ativar quando o usuário encontrar as seguintes situações na rede doméstica chinesa:

• git clone https://github.com/... lento, travando, Recv failure: Conexão redefinida pelo peer, timeout
• Acesso direto ao site / API do GitHub instável ou completamente bloqueado (curl https://github.com retorna 0 bytes)
• Necessidade de clonar vários repositórios, baixar arquivos de Release ou raw do GitHub

Ideia central: redirecionar as requisições a github.com para um "prefixo de aceleração (mirror proxy)" acessível diretamente da China, e fazer rotação automática + retry entre vários prefixos. Se um prefixo falhar, o sistema não trava; automaticamente tenta o próximo.

Instalação com um Comando

# Clone este repositório (use qualquer prefixo disponível para puxar o repositório primeiro)
git clone https://gh-proxy.com/https://github.com/OWNER/github-ghclone.git
cd github-ghclone
bash scripts/install.sh
source ~/.bashrc   # Para ativar ~/bin

Após a instalação, você terá:

• ~/bin/ghclone — script executável (rotação automática entre 3 prefixos, cada um com 3 tentativas)
• Aceleração global estática do Git url."https://gh-proxy.com/https://github.com/".insteadOf (beneficia diretamente os git clone comuns)
• Alias Git gclone → ghclone

Como Usar

# Modo 1: chamar o script diretamente
ghclone https://github.com/owner/repo.git --depth 1

# Modo 2: alias Git
git gclone https://github.com/owner/repo.git --depth 1

# Comando Git normal (já acelerado globalmente, não precisa de alias)
git clone https://github.com/owner/repo.git

ghclone detecta automaticamente qual prefixo está disponível no momento. Se tiver sucesso, retorna; se todos falharem, exibe erro.

Configuração Manual (caso não queira rodar install.sh)

1. Baixe o script (no repositório, o arquivo bin/ghclone), coloque em ~/bin/ e execute chmod +x.
2. Aceleração global estática do Git (escolha um prefixo atualmente disponível):

   git config --global url."https://gh-proxy.com/https://github.com/".insteadOf "https://github.com/"
   

3. Alias Git:

   git config --global alias.gclone '!~/bin/ghclone'
   

4. PATH: Garanta que ~/bin está no PATH (adicione ao ~/.bashrc):

   export PATH="$HOME/bin:$PATH"
   

Trocar / Adicionar/Remover Prefixos (quando um prefixo falhar)

Os prefixos de aceleração são proxies mantidos pela comunidade, instáveis; é necessário poder alterná-los:

• Edite o array PATS=(...) no arquivo ~/bin/ghclone (ou no arquivo bin/ghclone do repositório) para adicionar/remover prefixos.
• Para alterar o prefixo estático global do Git:

  # Trocar para um novo prefixo disponível
  git config --global url."https://novo-prefixo/https://github.com/".insteadOf "https://github.com/"
  # Remover o prefixo antigo
  git config --global --unset url."https://prefixo-antigo/https://github.com/".insteadOf
  

Verificar se um Prefixo Está Disponível

Para cada prefixo, teste clonando um pequeno repositório real (se retornar um commit hash, está disponível; se retornar 0 bytes/erro, está indisponível):

for p in https://gh-proxy.com https://ghfast.top https://ghproxy.net; do
  n=$(git ls-remote "$p/https://github.com/octocat/Hello-World.git" HEAD 2>/dev/null | head -1)
  echo "$p -> ${n:-Indisponível}"
done

Prefixos Conhecidos (testados em out/2026, sujeito a mudança)

Prefixo	Uso
https://gh-proxy.com	https://gh-proxy.com/https://github.com/owner/repo.git
https://ghfast.top	https://ghfast.top/https://github.com/owner/repo.git
https://ghproxy.net	https://ghproxy.net/https://github.com/owner/repo.git

A conexão direta com github.com na China geralmente retorna 0 bytes (bloqueado); é obrigatório usar prefixo. Os serviços de prefixo são instáveis; a lógica de retry do ghclone existe justamente para lidar com falhas transitórias como "conexão redefinida pelo peer".

Limitações e Observações

• Os proxies de prefixo são serviços de terceiros mantidos pela comunidade; disponibilidade, velocidade e tempo de vida são imprevisíveis; se todos falharem, é necessário encontrar novos prefixos para substituir PATS.
• Acelera apenas o acesso ao protocolo Git do github.com; subdomínios como objects.githubusercontent.com (arquivos grandes de Release) também podem ser encapsulados com prefixo, similarmente.
• Aviso de conformidade: certifique-se de utilizar métodos de acesso à internet de acordo com as regulamentações locais.