SourceHut do zero ao uso avançado: tutorial completo e didático

Este manual parte de uma situação concreta: você já criou sua conta no SourceHut, mas ainda precisa entender como as peças se encaixam e como trabalhar com elas sem depender de tentativa e erro. O objetivo é levá-lo da configuração inicial até um projeto completo, com repositório Git, tracker, lista de desenvolvimento, builds automáticos, documentação, página estática e ferramentas de linha de comando.

Os exemplos usam SEU_USUARIO, SEU_EMAIL e meu-projeto como marcadores. Substitua-os pelos seus dados. Nunca copie literalmente tokens, senhas ou chaves dos exemplos.

Regra de segurança: uma chave pública pode ser enviada ao SourceHut. A chave privada, o token de API e a senha do e-mail nunca devem entrar em repositórios, tickets, pastes ou logs de build.

Resumo executivo

Se você vem do GitHub ou GitLab, precisa mudar quatro ideias:

1. Um repositório não é automaticamente um projeto. O código mora em git.sr.ht; a página agregadora e pesquisável do projeto é criada separadamente no hub em sr.ht.
2. Contribuições são patches por e-mail, não pull requests. Você pode preparar o patchset pela interface web ou usar git send-email.
3. CI é descrita por um manifesto enviado para execução. Um arquivo .build.yml no repositório integra Git e builds.sr.ht.
4. Cada serviço é pequeno e especializado. Conta em meta.sr.ht, Git em git.sr.ht, tickets em todo.sr.ht, listas em lists.sr.ht, builds em builds.sr.ht, páginas em pages.sr.ht e assim por diante.

O caminho recomendado é:

1. proteger a conta com TOTP;
2. configurar nome, e-mail e chave SSH;
3. criar e publicar um repositório de teste;
4. criar um projeto no hub;
5. criar e vincular um tracker e uma lista;
6. adicionar um .build.yml;
7. aprender primeiro o preparador web de patches;
8. configurar git send-email;
9. instalar o cliente hut;
10. automatizar páginas, builds e exportações.

Metodologia e critérios

Este tutorial foi construído principalmente a partir dos manuais oficiais mantidos no repositório sr.ht-docs, da documentação atual da API GraphQL, da documentação do cliente hut, dos guias git-send-email.io, git-am.io e das páginas oficiais do srht.site.

Os comandos foram organizados para:

• explicar o que acontece antes de pedir que você execute algo;
• oferecer caminhos tanto pela interface web quanto pelo terminal;
• separar tarefas de proprietário, colaborador e mantenedor;
• mostrar alternativas para Windows, Fedora e Debian/Ubuntu;
• evitar segredos em linha de comando, histórico do shell e logs públicos;
• usar nomes genéricos que você possa substituir sem quebrar o exemplo.

SourceHut continua oficialmente em estágio alpha. Em 25 de julho de 2026, a página de status informava perturbação no git.sr.ht causada por crawlers agressivos. Isso não muda o funcionamento descrito aqui, mas é importante consultar status.sr.ht se operações web ou SSH estiverem instáveis.

1. O mapa mental do SourceHut

Os principais serviços

O ~ faz parte da identidade canônica de um usuário. Assim, o projeto meu-projeto do usuário pablo normalmente aparece como:

~pablo/meu-projeto

Um endereço de repositório SSH segue esta forma:

git@git.sr.ht:~pablo/meu-projeto

Repositório não é projeto

Criar ~SEU_USUARIO/meu-projeto em git.sr.ht cria apenas o repositório. Para que ele apareça na busca de projetos e reúna código, tickets e lista, crie também um projeto chamado meu-projeto no hub e vincule os recursos.

Essa separação permite configurações que outras forjas tornam difíceis:

• um projeto com vários repositórios;
• um tracker usado por mais de um projeto;
• uma lista pública que recebe patches de vários projetos pequenos;
• um projeto com Git e Mercurial;
• um projeto sem repositório, composto apenas por documentação e tickets.

2. Preparar seu computador

O que você precisa

Para os capítulos básicos:

• Git;
• um cliente OpenSSH com ssh, ssh-keygen e ssh-add;
• um editor de texto;
• acesso à sua conta de e-mail.

Para o fluxo de patches:

• git send-email;
• acesso SMTP ou um cliente sendmail compatível;
• de preferência um editor capaz de trabalhar com texto puro.

Para automação:

• hut, o cliente de terminal do SourceHut;
• opcionalmente jq, para filtrar respostas JSON;
• tar, curl e as ferramentas específicas do seu projeto.

Fedora

sudo dnf install git git-email openssh-clients hut jq

Verifique:

git --version
git send-email --help
ssh -V
hut version
jq --version

Debian e Ubuntu

sudo apt update
sudo apt install git git-email openssh-client jq

O pacote hut está disponível em versões recentes do Debian. Caso sua versão não o ofereça, use o binário ou as instruções de compilação do repositório oficial do hut.

sudo apt install hut

Windows

Instale o Git for Windows. O pacote oficial inclui as ferramentas de e-mail do Git. Você pode usar:

• PowerShell para Git e SSH;
• Git Bash para comandos Unix e git send-email;
• WSL para reproduzir quase exatamente o fluxo Linux.

Verifique no PowerShell:

git --version
git send-email --help
ssh -V

Se git send-email ou módulos Perl/SSL causarem problemas no Windows, use Git Bash ou WSL. O repositório continuará sendo o mesmo; apenas o ambiente de envio mudará.

O hut é mais simples no Fedora, Debian, Arch ou WSL. Ele é útil, mas não é obrigatório para começar: toda a configuração inicial pode ser feita pela web.

3. Proteger e completar a conta

Abra meta.sr.ht e revise as áreas a seguir.

Perfil

Em Profile, preencha somente o que deseja tornar público:

• nome de exibição;
• biografia em Markdown;
• URL pessoal;
• localização;
• pronomes.

Use o mesmo nome e e-mail que pretende registrar nos commits. Isso facilita a identificação de autoria nas listas.

Ativar TOTP

1. Abra Security.
2. Clique em Enable TOTP.
3. Leia o QR Code com Aegis, 2FAS, FreeOTP ou outro autenticador.
4. Digite um código atual para confirmar.
5. Guarde qualquer informação de recuperação fornecida.

O manual oficial alerta que, depois de ativar TOTP, a recuperação de senha pode exigir contato com o suporte. Proteja o autenticador e sua recuperação antes de encerrar a sessão.

Revisar o log de auditoria

A página de segurança mostra operações recentes e endereços IP. O serviço informa que esses registros são removidos após 14 dias. Consulte o log quando:

• cadastrar ou remover uma chave;
• autorizar um aplicativo;
• suspeitar de acesso indevido;
• trocar senha ou token.

Tokens e clientes autorizados

Em OAuth, você pode:

• revisar clientes autorizados;
• revogar integrações antigas;
• criar tokens pessoais para scripts e hut;
• registrar um cliente OAuth próprio.

Tokens pessoais documentados pelo SourceHut expiram em um ano. Anote a finalidade e a data de criação de cada token. Não use um token genérico em todos os servidores.

4. Criar e cadastrar sua chave SSH

O SourceHut não aceita git push por HTTPS com usuário e senha. Para enviar commits a git.sr.ht, use uma chave SSH.

Verificar se você já tem uma chave

Linux, macOS, Git Bash ou WSL:

ls -la ~/.ssh

PowerShell:

Get-ChildItem $HOME\.ssh

Arquivos terminados em .pub são chaves públicas. Arquivos sem .pub podem ser chaves privadas. Nunca publique o arquivo privado.

Criar uma chave dedicada ao SourceHut

Uma chave Ed25519 dedicada facilita revogação e identificação:

Linux, Git Bash ou WSL:

ssh-keygen -t ed25519 -a 64 -f ~/.ssh/id_ed25519_srht -C "SEU_EMAIL"

PowerShell:

ssh-keygen -t ed25519 -a 64 -f "$HOME/.ssh/id_ed25519_srht" -C "SEU_EMAIL"

Defina uma frase secreta. A frase protege a chave se o arquivo privado for copiado.

O comando cria:

~/.ssh/id_ed25519_srht      chave privada
~/.ssh/id_ed25519_srht.pub  chave pública

Copiar a chave pública

Linux, Git Bash ou WSL:

cat ~/.ssh/id_ed25519_srht.pub

PowerShell:

Get-Content $HOME\.ssh\id_ed25519_srht.pub | Set-Clipboard

Abra meta.sr.ht/keys, escolha a opção de chave SSH, cole a linha completa e salve.

Configurar qual chave usar

Crie ou edite ~/.ssh/config:

Host git.sr.ht
    HostName git.sr.ht
    User git
    IdentityFile ~/.ssh/id_ed25519_srht
    IdentitiesOnly yes

Host *.builds.sr.ht
    User builds
    IdentityFile ~/.ssh/id_ed25519_srht
    IdentitiesOnly yes

No Linux:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/config ~/.ssh/id_ed25519_srht
chmod 644 ~/.ssh/id_ed25519_srht.pub

Usar o ssh-agent

Linux, Git Bash ou WSL:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519_srht

PowerShell, quando o serviço ssh-agent já estiver habilitado:

Start-Service ssh-agent
ssh-add $HOME\.ssh\id_ed25519_srht

Verificar a conexão

ssh -vT git@git.sr.ht

Na primeira conexão, confira a chave do host com a seção SSH host keys da documentação oficial do git.sr.ht antes de aceitar. O SourceHut não fornece um shell interativo nesse endereço; portanto, uma sessão encerrada depois da autenticação não significa necessariamente erro. No diagnóstico -v, procure a confirmação de autenticação por chave pública.

5. Configurar o Git corretamente

Defina sua identidade:

git config --global user.name "SEU NOME"
git config --global user.email "SEU_EMAIL"

Escolha main para novos repositórios:

git config --global init.defaultBranch main

Defina um editor. Exemplos:

git config --global core.editor "nano"

git config --global core.editor "code --wait"

Revise:

git config --global --list

Não copie configurações SMTP ou credenciais para um arquivo .gitconfig publicado. O arquivo global normalmente fica no seu perfil de usuário, não no repositório.

6. Criar seu primeiro repositório

Caminho recomendado: criar primeiro na web

1. Abra git.sr.ht/create.
2. Digite meu-projeto.
3. Adicione uma descrição de uma linha.
4. Escolha a visibilidade:
   • public: público e encontrável;
   • unlisted: acessível pelo endereço, mas não promovido na descoberta;
   • private: restrito ao proprietário e acessos concedidos.
5. Crie o repositório.

Criar o projeto local

Linux, Git Bash ou WSL:

mkdir meu-projeto
cd meu-projeto
git init
printf "# Meu projeto\n\nDescrição curta.\n" > README.md

PowerShell:

New-Item -ItemType Directory meu-projeto
Set-Location meu-projeto
git init
Set-Content README.md "# Meu projeto`n`nDescrição curta."

Adicione uma licença apropriada ao projeto. Não invente uma licença nem copie uma sem entender seus termos.

git add README.md
git commit -m "Initial commit"

Conectar ao SourceHut

git remote add origin "git@git.sr.ht:~SEU_USUARIO/meu-projeto"
git push -u origin main

O -u associa a branch local main à remota. Depois disso, bastará:

git push

Conferir o resultado

git remote -v
git status
git branch -vv

Abra:

https://git.sr.ht/~SEU_USUARIO/meu-projeto

O README.md deve aparecer na página inicial do repositório.

Atalho: criar durante o primeiro push

O SourceHut também aceita um fluxo em que você adiciona o remote e tenta publicar antes de criar o repositório. Ele devolve um link para a tela de criação. Para aprender, prefira a criação web explícita; ela deixa nome, visibilidade e descrição mais claros.

7. Publicar um repositório já existente

Entre no repositório local:

cd caminho/do/projeto
git status
git log --oneline -5

Crie o repositório vazio no SourceHut. Depois, decida se ele será o remote principal ou um espelho adicional.

Tornar SourceHut o remote principal

Se ainda não existe origin:

git remote add origin "git@git.sr.ht:~SEU_USUARIO/meu-projeto"
git push -u origin main
git push --tags

Se origin aponta para outra forja:

git remote rename origin antigo
git remote add origin "git@git.sr.ht:~SEU_USUARIO/meu-projeto"
git push -u origin --all
git push origin --tags

Usar SourceHut como segundo remote

git remote add sourcehut "git@git.sr.ht:~SEU_USUARIO/meu-projeto"
git push sourcehut --all
git push sourcehut --tags

Confira:

git remote -v

Não use --mirror sem entender que ele envia e pode remover todas as refs para igualar o destino à origem.

8. Clonar, atualizar e trabalhar no dia a dia

Clonar por SSH

git clone "git@git.sr.ht:~SEU_USUARIO/meu-projeto"
cd meu-projeto

Clonar um projeto público por HTTPS

git clone "https://git.sr.ht/~OUTRO_USUARIO/projeto"

HTTPS é ótimo para leitura. Para publicar no seu repositório, use remote SSH.

Rotina segura de trabalho

git switch main
git pull --ff-only
git switch -c minha-mudanca

Depois de editar:

git status
git diff
git add caminho/do/arquivo
git diff --cached
git commit

Antes de publicar:

git log --oneline --decorate -5
git push -u origin minha-mudanca

No fluxo tradicional do SourceHut, publicar uma branch não cria uma pull request. A branch pode servir como backup ou referência, mas a contribuição formal normalmente é enviada como patchset por e-mail.

9. Administrar um repositório

README, licença e estrutura mínima

O SourceHut renderiza README, README.md ou README.markdown. Um repositório novo deveria explicar:

• o que o projeto resolve;
• o estado atual;
• como instalar ou executar;
• como testar;
• como contribuir;
• onde reportar problemas;
• qual licença se aplica.

Estrutura inicial útil:

meu-projeto/
├── README.md
├── LICENSE
├── CONTRIBUTING.md
├── .gitignore
├── .build.yml
└── src/

O SourceHut reconhece nomes como LICENSE, COPYING, COPYRIGHT e LICENSES. Projetos com múltiplas licenças podem usar a organização da especificação REUSE.

Alterar descrição e visibilidade

Abra o repositório e entre em settings. Revise:

• nome;
• descrição;
• visibilidade;
• branch padrão;
• acessos;
• webhooks;
• exclusão.

Alterar de privado para público torna histórico, refs e conteúdo acessíveis. Faça uma revisão de segredos antes.

Conceder acesso a um colaborador

Na área de acesso do repositório, adicione o nome canônico do usuário, por exemplo ~alice, e escolha:

• RO: leitura de repositório privado;
• RW: leitura e escrita.

Não conceda RW apenas para permitir que alguém proponha uma mudança. Qualquer pessoa pode enviar patches sem receber escrita no seu repositório.

Trocar a branch padrão

Pela web, escolha a nova branch em settings. Pelo Git, para renomear master como main:

git branch -m master main
git push -u origin main

Depois de selecionar main como padrão no SourceHut:

git push origin --delete master

Só apague a antiga depois de confirmar que CI, scripts e colaboradores já usam a nova.

Tags e releases

Crie uma tag anotada:

git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

Tags anotadas aparecem em refs. Ao abrir uma tag, você pode anexar arquivos como binários, checksums e assinaturas. O código-fonte em tar.gz também é gerado a partir da tag.

Uma rotina simples:

git shortlog v0.9.0..v1.0.0
git tag -a v1.0.0
git push --follow-tags

Você pode tornar o envio de tags anotadas automático:

git config --global push.followTags true

Opções especiais de push

git.sr.ht aceita opções com git push -o:

git push -o skip-ci
git push -o visibility=unlisted
git push -o description="Descrição curta"
git push -o debug

Usos:

• skip-ci: não envia builds para aquele push;
• visibility: muda para public, unlisted ou private;
• description: atualiza a descrição;
• debug: imprime o UUID do push para suporte.

Use com cuidado. Uma opção permanente pode ser configurada no repositório:

git config --add push.pushOption submit=".sourcehut/*.yml"

Limites e bom uso

A documentação sugere manter repositórios, aproximadamente, abaixo do tamanho do repositório do kernel Linux, cerca de 6 GiB, e evitar grandes quantidades de áudio, vídeo, imagens e outros binários. Git não é armazenamento de mídia.

Automações em massa devem limitar operações Git a aproximadamente uma por minuto. Para acompanhar mudanças, prefira webhooks a polling.

10. Criar um projeto no hub

O projeto é a página que transforma recursos separados em uma unidade encontrável.

Criar pela web

1. Abra sr.ht.
2. Entre em projects.
3. Escolha create project.
4. Use o nome meu-projeto.
5. Escreva uma descrição que explique valor e público.
6. Escolha visibilidade.
7. Adicione tags úteis.
8. Salve.

Vincular recursos

Na configuração do projeto, adicione:

• o repositório ~SEU_USUARIO/meu-projeto;
• o tracker ~SEU_USUARIO/meu-projeto;
• a lista ~SEU_USUARIO/meu-projeto-devel;
• outros repositórios, trackers ou listas relacionados.

Defina qual repositório fornecerá o README mostrado na página do projeto.

Tags sensatas

Use tags que ajudem alguém a encontrar a finalidade:

#self-hosting #cli #backup

Evite dezenas de tags de linguagem e plataforma que não mudam a essência. O manual recomenda observar termos já usados pela comunidade para não fragmentar categorias.

Por que a vinculação é funcional

Ela não serve apenas para decoração. Recursos dentro do mesmo projeto permitem:

• commits fecharem ou referenciarem tickets;
• patches enviados à lista dispararem builds;
• visitantes descobrirem toda a infraestrutura do projeto;
• uma lista atender vários repositórios com prefixos diferentes.

11. Criar e usar um tracker em todo.sr.ht

Criar o tracker

1. Abra todo.sr.ht.
2. Clique para criar um tracker.
3. Use meu-projeto.
4. Escreva a finalidade do tracker.
5. Escolha Create & configure.
6. Defina permissões para visitantes, usuários autenticados e autores.
7. Vincule o tracker ao projeto no hub.

Permissões

Pense em ações diferentes:

• navegar;
• enviar ticket;
• comentar;
• fazer triagem;
• administrar.

Um projeto público costuma permitir navegação, abertura e comentário, enquanto triagem fica restrita a mantenedores.

Criar um ticket

Escreva um título específico:

Falha ao importar arquivo UTF-8 com BOM

No corpo, inclua:

## Ambiente

- versão: 1.2.0
- sistema: Fedora 44
- comando: `meu-programa importar exemplo.csv`

## Passos para reproduzir

1. Criar arquivo UTF-8 com BOM.
2. Executar o comando.
3. Observar a mensagem.

## Resultado esperado

O arquivo deveria ser importado.

## Resultado atual

O programa retorna `invalid header`.

Nunca cole tokens ou dumps com dados pessoais.

Labels

Uma taxonomia inicial:

• bug;
• feature;
• documentation;
• security;
• needs-info;
• good-first-task.

Evite criar labels que ninguém usará. Cor não substitui um nome claro.

Busca

Exemplos:

status:open
label:bug status:open
assigned:me
no:assignee
!assigned:me
submitter:me
sort:updated
rsort:created
sort:comments sort:created

Negue um filtro com !.

Menções

~alice
#42
meu-projeto#42
~outro/tracker#42

Referenciar e fechar tickets por commit

Adicione trailers ao final da mensagem:

parser: aceitar BOM em arquivos CSV

Remove o marcador antes da detecção do cabeçalho.

Fixes: https://todo.sr.ht/~SEU_USUARIO/meu-projeto/42

Outras chaves:

References:
Implements:
Closes:

Para o fechamento automático funcionar:

1. repositório e tracker devem estar no mesmo projeto do hub;
2. a pessoa que publica o commit precisa de acesso de triagem ao tracker.

Usar o tracker por e-mail

Criar ticket:

~SEU_USUARIO/meu-projeto@todo.sr.ht

Comentar no ticket 42:

~SEU_USUARIO/meu-projeto/42@todo.sr.ht

Se seu provedor rejeitar ~ ou /, use o formato alternativo exibido pelo SourceHut:

u.SEU_USUARIO.meu-projeto@todo.sr.ht

Usuários com triagem podem colocar na última linha:

!resolve fixed

Resoluções documentadas:

fixed
implemented
wont_fix
by_design
invalid
duplicate
not_our_bug

Para reabrir:

!reopen

Envie texto puro e remova conteúdo citado que não contribui ao comentário.

12. Criar e administrar uma lista de e-mail

Para que a lista serve

Uma lista pode receber:

• patches;
• revisão técnica;
• propostas de arquitetura;
• dúvidas de desenvolvimento;
• anúncios;
• relatos privados de segurança, com permissões especiais.

Para um projeto, use nomes explícitos:

meu-projeto-devel
meu-projeto-announce
meu-projeto-security

Criar pela web

1. Abra lists.sr.ht.
2. Crie meu-projeto-devel.
3. Descreva o assunto e as regras.
4. Defina visibilidade e permissões.
5. Vincule a lista ao projeto no hub.
6. Publique o endereço em CONTRIBUTING.md.

O endereço normal será:

~SEU_USUARIO/meu-projeto-devel@lists.sr.ht

Inscrever e sair por e-mail

~SEU_USUARIO/meu-projeto-devel+subscribe@lists.sr.ht
~SEU_USUARIO/meu-projeto-devel+unsubscribe@lists.sr.ht

Também é possível usar os controles da interface.

Etiqueta obrigatória

1. Envie texto puro, não HTML.
2. Responda abaixo ou entre os trechos citados, não no topo.
3. Remova citações irrelevantes.
4. Quebre linhas por volta de 72 colunas.
5. Use Reply All para manter lista e participantes.
6. Não altere o assunto de modo que quebre a conversa.
7. Explique o raciocínio, não apenas “não funciona”.

Exemplo de resposta correta:

> O parser remove o BOM depois de ler o cabeçalho.

Acho melhor remover antes da detecção. Assim a comparação do primeiro
campo não precisa conhecer esse caso especial.

Arquivo e busca

No arquivo da lista, pesquise por:

from:me
is:patch
"texto exato"
message-id:<identificador>
In-Reply-To:<identificador>

Uma conversa pode se ramificar. Responda à mensagem específica cujo trecho está revisando.

Exportar mbox

Em uma thread, use Export thread (mbox). O arquivo reúne as mensagens e pode ser aplicado com git am.

Lista somente para anúncios

Remova de usuários comuns as permissões de publicar e responder. Proprietários continuam podendo publicar. Não deixe respostas públicas se pretende um canal unidirecional.

Caixa de segurança com escrita pública e leitura privada

Para relatos de vulnerabilidade:

• permita publicar;
• remova a permissão pública de navegar;
• restrinja leitura e resposta aos mantenedores.

Teste essa configuração com uma conta externa antes de divulgar o endereço.

13. Enviar patches pela interface web

Este é o melhor primeiro contato para quem conhece pull requests, mas ainda não configurou SMTP.

Preparar o código

1. Clone o projeto ou use Clone repo to your account.
2. Faça as mudanças localmente.
3. Organize commits pequenos e coerentes.
4. Publique os commits no seu repositório do SourceHut.
5. Abra a página desse repositório.

Abrir o preparador

Clique em Prepare a patchset.

1. Selecione o commit mais antigo que fará parte.
2. Selecione o commit mais novo.
3. Decida se haverá carta de apresentação.
4. Acrescente comentários que ajudem a revisão, mas não pertencem ao histórico.
5. Use revisão 1 na primeira versão.

Carta de apresentação

Para vários commits, explique:

• o problema;
• por que a mudança é necessária;
• como os commits estão organizados;
• como você testou;
• limitações conhecidas.

Ela é o equivalente mais próximo do título e da descrição de uma pull request.

Destinatários

No campo To, use a lista indicada em README ou CONTRIBUTING.md.

No Cc, inclua pessoas relevantes somente quando houver razão. git blame ajuda a encontrar quem trabalhou recentemente na área:

git blame caminho/do/arquivo

Revise as mensagens geradas e envie.

Receber feedback e criar v2

1. Responda às perguntas por e-mail.
2. Edite os commits, em vez de acrescentar commits “fix review”.
3. Use git commit --amend para o último commit.
4. Use git rebase -i para uma série.
5. Atualize sua branch remota:

git push --force-with-lease

1. Prepare o patchset novamente.
2. Mude a revisão para 2.
3. Resuma o que mudou desde v1.

Prefira --force-with-lease a --force: ele reduz o risco de apagar mudanças remotas que você ainda não viu.

14. Enviar patches com git send-email

Este fluxo parece estranho no início, mas usa objetos nativos do Git. Cada commit vira uma mensagem; uma série vira uma thread.

Confirmar a instalação

git send-email --help

Se não existir:

Fedora:

sudo dnf install git git-email

Debian ou Ubuntu:

sudo apt install git git-email

Git for Windows inclui as ferramentas de e-mail. No Arch, o pacote git inclui o comando, acompanhado dos módulos Perl de SASL e SSL.

Configurar SMTP genérico

Descubra na documentação do seu provedor:

• servidor SMTP;
• porta;
• TLS direto ou STARTTLS;
• usuário;
• método de autenticação;
• uso de senha de aplicativo ou OAuth.

Exemplo com TLS direto:

git config --global sendemail.smtpServer "mail.example.org"
git config --global sendemail.smtpUser "SEU_EMAIL"
git config --global sendemail.smtpEncryption ssl
git config --global sendemail.smtpServerPort 465

Exemplo com STARTTLS:

git config --global sendemail.smtpServer "mail.example.org"
git config --global sendemail.smtpUser "SEU_EMAIL"
git config --global sendemail.smtpEncryption tls
git config --global sendemail.smtpServerPort 587

Não grave sua senha diretamente no .gitconfig se puder usar prompt, helper de credenciais, msmtp, chaveiro ou OAuth.

Gmail

O guia oficial recomenda 2FA e uma senha de aplicativo:

git config --global sendemail.smtpServer smtp.gmail.com
git config --global sendemail.smtpUser "SEU_EMAIL@gmail.com"
git config --global sendemail.smtpEncryption ssl
git config --global sendemail.smtpServerPort 465

Forneça a senha de aplicativo quando solicitada. Políticas do Google podem mudar; confirme na documentação da conta.

Outlook e provedores que exigem OAuth 2.0

Configuração de transporte típica:

git config --global sendemail.smtpServer smtp.office365.com
git config --global sendemail.smtpUser "SEU_EMAIL"
git config --global sendemail.smtpEncryption tls
git config --global sendemail.smtpServerPort 587
git config --global sendemail.smtpAuth XOAUTH2

XOAUTH2 exige um adaptador de credenciais compatível, como o git-credential-email citado no guia oficial, e módulos Perl adequados. Não substitua o token OAuth por sua senha comum.

Usar msmtp

Se você já configurou msmtp:

git config --global sendemail.sendmailCmd "/usr/bin/msmtp -a desenvolvimento"

Essa opção evita colocar detalhes SMTP em várias ferramentas.

Configurar a lista por repositório

Dentro do clone:

git config sendemail.to "~DONO/lista-devel@lists.sr.ht"
git config sendemail.annotate yes

Se uma lista atende vários repositórios:

git config format.subjectPrefix "PATCH meu-projeto"

Verifique:

git config --local --get-regexp "sendemail|format.subject"

Preparar uma mudança de um commit

git switch -c corrigir-bom
# edite e teste
git add src/parser.py tests/test_parser.py
git diff --cached
git commit

Mensagem:

parser: aceitar UTF-8 com BOM

Remove o marcador antes da análise do cabeçalho e adiciona um teste
de regressão.

Fixes: https://todo.sr.ht/~DONO/meu-projeto/42

Inspecionar o patch sem enviar

git format-patch --stdout origin/main..HEAD

Procure:

• arquivos acidentais;
• segredos;
• commits de depuração;
• mensagem incompleta;
• testes ausentes;
• linhas geradas ou binários.

Fazer um ensaio

git send-email --dry-run origin/main..HEAD

Confira remetente, destinatário, assunto e quantidade de mensagens.

Enviar

git send-email --annotate origin/main..HEAD

O editor abrirá cada mensagem. Texto depois do separador --- pode explicar teste e contexto sem entrar no commit.

Para explicitar o destino:

git send-email \
  --to="~DONO/lista-devel@lists.sr.ht" \
  --annotate \
  origin/main..HEAD

Enviar uma série com carta de apresentação

git send-email --cover-letter --annotate origin/main..HEAD

Edite o assunto de [PATCH 0/N] e substitua o texto de exemplo. Explique a motivação e a ordem da série.

Enviar v2

Primeiro, corrija os commits:

git rebase -i origin/main

Depois:

git send-email --annotate -v2 origin/main..HEAD

No comentário depois de ---, escreva:

Changes since v1:
- corrige o tratamento de arquivo vazio;
- adiciona teste para BOM seguido de cabeçalho sem colunas.

Não misture a lista de mudanças da revisão com a mensagem permanente do commit.

Sign-off

Alguns projetos exigem:

git commit --signoff

ou:

git config format.signOff true

Signed-off-by não é uma assinatura criptográfica. Seu significado depende do projeto, frequentemente relacionado ao Developer Certificate of Origin. Só use depois de ler a política.

Erros comuns

• enviar HTML em vez de texto puro;
• criar patch por copiar e colar um git diff no webmail;
• esquecer Reply All;
• enviar v2 sem -v2;
• acrescentar commits que consertam commits anteriores;
• não testar a série sobre a branch atual do mantenedor;
• incluir segredo em patch ou log.

15. Revisar e aplicar patches como mantenedor

Revisar na lista

Abra a thread e:

1. leia a carta de apresentação;
2. veja a ordem dos commits;
3. abra cada patch;
4. responda à linha específica;
5. indique se o problema é funcional, de estilo ou apenas sugestão;
6. mantenha a lista em cópia.

Uma revisão útil:

> +if data.startswith(BOM):
> +    data = data[3:]

Este corte assume três bytes. Podemos usar a constante já definida em
encoding.py para deixar a intenção explícita?

Baixar a thread em mbox

Na lateral da thread, use Export thread (mbox) e salve como:

patchset.mbox

Aplicar com git am

Crie uma branch de teste:

git switch main
git pull --ff-only
git switch -c revisar-patchset
git am patchset.mbox

Teste:

git log --oneline --decorate -5
git show --stat
# execute os testes do projeto

Conflitos

Veja o patch atual:

git am --show-current-patch=diff
git status

Resolva arquivos, depois:

git add arquivos-resolvidos
git am --continue

Para cancelar tudo:

git am --abort

Tente mesclagem de três vias:

git am -3 patchset.mbox

Conflito pode indicar que o patch precisa ser reenviado sobre uma base atual. Não faça grandes correções silenciosas no trabalho do autor.

Publicar

Depois de revisar autoria, testes e histórico:

git switch main
git merge --ff-only revisar-patchset
git push origin main

Responda à thread informando que foi aplicado. A interface e a API também permitem marcar o patchset como APPLIED, APPROVED, NEEDS_REVISION, REJECTED ou SUPERSEDED.

16. Builds e integração contínua

builds.sr.ht executa manifests YAML em máquinas virtuais efêmeras. O job não precisa estar permanentemente cadastrado nem preso a um repositório.

Custo: a página oficial de preços informa que builds.sr.ht e chat.sr.ht exigem conta paga durante o estágio alpha. Os planos têm o mesmo acesso e variam pelo valor que o usuário escolhe pagar.

Primeiro job pela web

Abra builds.sr.ht/submit e cole:

image: alpine/latest
tasks:
  - hello: |
      echo "Olá, SourceHut Builds"
      uname -a

Adicione uma nota e envie. O sistema:

1. escolhe um runner;
2. inicia uma VM;
3. prepara o ambiente;
4. executa as tarefas na ordem;
5. preserva logs e resultado.

Anatomia de um manifesto

image: alpine/latest
arch: x86_64
packages:
  - git
sources:
  - https://git.sr.ht/~SEU_USUARIO/meu-projeto
environment:
  MODO: teste
tasks:
  - verificar: |
      cd meu-projeto
      echo "$MODO"
      git status
artifacts:
  - meu-projeto/resultado.tar.gz

Campos:

• image: sistema operacional;
• arch: arquitetura, quando necessário;
• packages: dependências instaladas pelo sistema;
• sources: repositórios clonados;
• environment: variáveis gravadas em ~/.buildenv;
• tasks: scripts executados em ordem;
• artifacts: arquivos coletados depois de job bem-sucedido;
• secrets: UUIDs de segredos;
• oauth: token temporário com permissões pedidas;
• triggers: e-mail ou webhook pós-build;
• submitter: regras para integrações;
• shell: mantém acesso SSH para depuração.

Cada tarefa roda em uma nova sessão de login. Arquivos permanecem, mas um cd feito numa tarefa não muda o diretório inicial da próxima.

CI automático no repositório

Na raiz, crie .build.yml:

image: alpine/latest
packages:
  - make
  - gcc
  - musl-dev
sources:
  - https://git.sr.ht/~SEU_USUARIO/meu-projeto
tasks:
  - build: |
      cd meu-projeto
      make
  - test: |
      cd meu-projeto
      make check

Depois:

git add .build.yml
git commit -m "ci: add SourceHut build"
git push

git.sr.ht detecta .build.yml, substitui a origem pela ref do push e envia o job.

Testar várias plataformas

Crie até quatro manifests:

.builds/alpine.yml
.builds/debian.yml
.builds/fedora.yml
.builds/freebsd.yml

Se houver mais de quatro, a documentação informa que quatro podem ser escolhidos aleatoriamente por push. Mantenha no máximo quatro manifests automáticos.

Exemplo Node.js

image: alpine/latest
packages:
  - nodejs
  - npm
sources:
  - https://git.sr.ht/~SEU_USUARIO/app-node
tasks:
  - install: |
      cd app-node
      npm ci
  - test: |
      cd app-node
      npm test
  - build: |
      cd app-node
      npm run build
artifacts:
  - app-node/dist.tar.gz

Se deseja dist.tar.gz, sua etapa build precisa realmente criá-lo:

  - package: |
      cd app-node
      tar -czf dist.tar.gz dist

Exemplo Python

image: ubuntu/lts
packages:
  - python3
  - python3-venv
sources:
  - https://git.sr.ht/~SEU_USUARIO/app-python
tasks:
  - test: |
      cd app-python
      python3 -m venv .venv
      . .venv/bin/activate
      pip install -r requirements.txt
      pytest

Se pytest não estiver em requirements.txt, use um arquivo de dependências de desenvolvimento ou instale-o explicitamente no ambiente virtual.

Exemplo Rust

image: alpine/latest
packages:
  - rust
  - cargo
sources:
  - https://git.sr.ht/~SEU_USUARIO/app-rust
tasks:
  - format: |
      cd app-rust
      cargo fmt --check
  - test: |
      cd app-rust
      cargo test --locked
  - build: |
      cd app-rust
      cargo build --release --locked

Adicione o componente ou pacote necessário para rustfmt se a imagem escolhida não o incluir.

Restringir builds a main e tags

submitter:
  git.sr.ht:
    enabled: true
    allow-refs:
      - refs/heads/main
      - "refs/tags/*"

Variáveis fornecidas pela integração Git:

BUILD_SUBMITTER=git.sr.ht
GIT_REF=refs/heads/main

Pular um build

git push -o skip-ci

Artefatos

artifacts:
  - meu-projeto/release.tar.gz
  - meu-projeto/checksums.txt

Caminhos são literais e relativos ao diretório pessoal da VM. ~ e glob não são expandidos. Artefatos só são enviados em jobs bem-sucedidos e a documentação informa retenção de 90 dias. Publique releases permanentes como anexos de tags.

E-mail ao final

triggers:
  - action: email
    condition: failure
    to: SEU_EMAIL

Webhook ao final

triggers:
  - action: webhook
    condition: always
    url: https://example.org/hooks/sourcehut

O endpoint deve validar a origem e tratar reenvios. Não coloque um segredo na URL se ela aparecer no manifesto público.

Depurar por SSH

Adicione:

shell: true

Durante ou depois do job, a interface mostra o comando:

ssh -t builds@SERVIDOR.builds.sr.ht connect ID_DO_JOB

Em falhas, a documentação oferece uma janela adicional para conexão. Use-a para inspecionar ambiente e comandos; não transforme a VM efêmera em servidor.

17. Segredos em builds

Segredos podem ser:

• chave SSH de deploy;
• chave PGP;
• arquivo de configuração;
• credencial usada para publicar.

Regra mais importante

As tarefas são executadas com set -x. Comandos e variáveis expandidas podem aparecer no log. Não faça:

echo "$TOKEN"
curl -H "Authorization: Bearer $TOKEN" ...

Se não houver alternativa:

set +x
# comando que usa o segredo
set -x

Também impeça a própria ferramenta de imprimir a credencial.

Chave de deploy para um servidor

Crie uma conta de deploy com acesso mínimo no servidor de destino. Gere uma chave exclusiva e sem passphrase para a automação:

ssh-keygen -t ed25519 -f ./deploy_srht -C "builds.sr.ht deploy"

Instale deploy_srht.pub no authorized_keys do usuário de deploy. Restrinja permissões, diretórios e comandos no servidor.

Em builds.sr.ht/secrets:

1. escolha SSH key;
2. cole a chave privada deploy_srht;
3. salve;
4. copie o UUID;
5. apague a cópia local privada se ela não deve permanecer.

No manifesto:

secrets:
  - UUID_DO_SEGREDO

O UUID identifica o segredo; ele não é o conteúdo secreto. Mesmo assim, documente sua finalidade.

Repositório privado

Para clonar um repositório privado no build:

1. gere uma chave de CI sem passphrase;
2. cadastre a chave pública em meta.sr.ht/keys;
3. cadastre a privada como segredo do build;
4. use origem SSH.

image: alpine/latest
secrets:
  - UUID_DA_CHAVE
sources:
  - git@git.sr.ht:~SEU_USUARIO/repositorio-privado
tasks:
  - test: |
      cd repositorio-privado
      make check

Patches externos não recebem seus segredos

Builds disparados por patches enviados a uma lista vinculada têm segredos desativados. Essa é uma proteção essencial: um estranho não pode mudar o manifesto para imprimir sua chave.

Seu build deve falhar de maneira compreensível ou pular etapas de deploy quando o segredo não existe.

Vazamento

Se um segredo aparecer em build público ou não listado:

1. considere-o comprometido;
2. revogue no serviço de origem;
3. gere outro;
4. substitua no SourceHut;
5. investigue uso;
6. corrija o manifesto.

A política documentada não promete apagar logs para “desvazar” uma chave.

18. Testar patches recebidos automaticamente

Quando repositório, lista e .build.yml pertencem ao mesmo projeto do hub:

1. o colaborador envia [PATCH meu-projeto];
2. o hub associa o prefixo ao repositório;
3. o patch é aplicado em ambiente de teste;
4. o build é enviado;
5. o resultado volta à thread.

Configure o prefixo:

git config format.subjectPrefix "PATCH meu-projeto"

Variáveis disponíveis:

BUILD_SUBMITTER=hub.sr.ht
BUILD_REASON=patchset
PATCHSET_ID=...
PATCHSET_URL=...

Desative somente se necessário:

submitter:
  hub.sr.ht:
    enabled: false

Lembre-se: segredos permanecem desligados nesse tipo de build.

19. Publicar um site em pages.sr.ht

Todo usuário recebe:

SEU_USUARIO.srht.site

O serviço aceita conteúdo estático: HTML, CSS, JavaScript, imagens e arquivos. Não executa PHP, Node.js, Python ou banco de dados no servidor.

Publicação manual com hut

Crie:

<!doctype html>
<html lang="pt-BR">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Meu site no SourceHut</title>
<h1>Olá, SourceHut Pages</h1>
<p>Meu primeiro site estático.</p>

Salve como index.html. Empacote:

tar -czf site.tar.gz index.html

Publique:

hut pages publish \
  -d SEU_USUARIO.srht.site \
  site.tar.gz

Acesse:

https://SEU_USUARIO.srht.site

Na primeira visita, o TLS pode levar alguns segundos.

Empacotar a saída de um gerador

Hugo:

hugo
tar -C public -czf site.tar.gz .
hut pages publish -d SEU_USUARIO.srht.site site.tar.gz

O ponto após -C public coloca o conteúdo de public na raiz do tarball. Evite publicar uma pasta public/ extra que faria o site começar em /public/.

Publicar com curl

Crie um token com escopo pages.sr.ht/PAGES:RW e mantenha-o fora do histórico. Uma forma temporária:

read -rsp "Token: " SOURCEHUT_TOKEN
export SOURCEHUT_TOKEN
echo

Publique:

curl \
  --oauth2-bearer "$SOURCEHUT_TOKEN" \
  -F content=@site.tar.gz \
  "https://pages.sr.ht/publish/SEU_USUARIO.srht.site"

Depois:

unset SOURCEHUT_TOKEN

Não coloque o token diretamente no comando, porque ele pode aparecer no histórico e na lista de processos.

Deploy automático com build

Crie .build.yml no repositório do site:

image: alpine/latest
oauth: pages.sr.ht/PAGES:RW
packages:
  - hut
  - hugo
environment:
  site: SEU_USUARIO.srht.site
sources:
  - https://git.sr.ht/~SEU_USUARIO/meu-site
tasks:
  - build: |
      cd meu-site
      hugo
  - package: |
      cd meu-site/public
      tar -czf ../../site.tar.gz .
  - publish: |
      hut pages publish -d "$site" site.tar.gz
submitter:
  git.sr.ht:
    enabled: true
    allow-refs:
      - refs/heads/main

O campo oauth cria para o job um token temporário limitado a publicar páginas. É preferível a armazenar um token pessoal como segredo.

Domínio próprio

Para subdomínio, crie CNAME:

site IN CNAME pages.sr.ht.

Depois:

hut pages publish -d site.example.org site.tar.gz

Para domínio raiz, o serviço publica endereços A e AAAA na documentação de domínios personalizados. Não copie IPs de um tutorial antigo: confirme os valores oficiais no dia da configuração, pois podem mudar.

Configuração de 404 e cache

Crie siteconfig.json:

{
  "notFound": "404.html",
  "fileConfigs": [
    {
      "glob": "*.png",
      "options": {
        "cacheControl": "max-age=15552000"
      }
    },
    {
      "glob": "*.css",
      "options": {
        "cacheControl": "max-age=7200"
      }
    }
  ]
}

Publique:

hut pages publish \
  -d site.example.org \
  --site-config siteconfig.json \
  site.tar.gz

Atualizar só um subdiretório

hut pages publish \
  -d site.example.org \
  --subdirectory docs \
  docs.tar.gz

O restante do site é preservado.

Limitações

Em 25 de julho de 2026, a documentação informava:

• tarball limitado a 1 GiB depois da descompressão;
• symlinks e entradas que não sejam arquivos regulares são ignorados;
• scripts e estilos externos por CDN são bloqueados;
• rastreadores não são permitidos;
• mídia externa precisa de HTTPS;
• target="_blank" externo é bloqueado pela política de segurança;
• HTTPS é fornecido automaticamente.

Hospede CSS, JavaScript e fontes no próprio site.

20. Criar documentação em man.sr.ht

man.sr.ht é uma wiki cujo conteúdo vem de um repositório Git.

Criar

1. Abra man.sr.ht.
2. Faça login.
3. Use create wiki.
4. Dê nome e visibilidade.
5. Clone o repositório indicado.

Estrutura

docs/
├── index.md
├── instalacao.md
├── configuracao/
│   ├── index.md
│   └── email.md
└── troubleshooting.md

Somente Markdown é publicado. Imagens, HTML e outros arquivos não são servidos pela wiki conforme o manual atual.

index.md vira a página do diretório. Outras páginas mantêm o caminho do arquivo.

Frontmatter

---
title: "Instalação"
toc: true
---

Propriedades documentadas:

• title;
• toc, que pode ser false.

Publicar

git add .
git commit -m "docs: add installation guide"
git push

A wiki recompila a partir do Git.

Visibilidade

A visibilidade da wiki é independente da visibilidade do repositório que a alimenta. É possível manter o repositório privado e a documentação pública. Revise as duas configurações.

Quando usar man e quando usar pages

Use man.sr.ht para:

• documentação Markdown;
• manual técnico;
• edição e colaboração por Git;
• sumário automático.

Use pages.sr.ht para:

• landing page;
• blog gerado;
• documentação com tema próprio;
• CSS, JavaScript, imagens e domínio personalizado.

21. Usar paste.sr.ht

Abra paste.sr.ht, cole o texto, dê um nome opcional e escolha a visibilidade.

Usos adequados:

• log sanitizado;
• exemplo mínimo;
• trecho de configuração sem segredo;
• saída de diagnóstico;
• arquivo pequeno para discussão.

Não use para:

• token;
• senha;
• chave privada;
• dump de produção;
• informação pessoal;
• armazenamento permanente.

O botão View raw fornece conteúdo direto para curl ou wget.

Com hut:

hut paste create exemplo.log

Via pipe:

comando 2>&1 | hut paste create --name diagnostico.txt

Antes do pipe, revise se a saída pode conter variáveis, caminhos pessoais, headers, cookies ou credenciais.

22. Usar chat.sr.ht e o bouncer Soju

chat.sr.ht é um bouncer IRC, não uma rede IRC. Ele mantém conexões com redes como Libera Chat enquanto seus dispositivos ficam offline.

O serviço é documentado como disponível para contas pagas.

Caminho mais simples

1. Abra chat.sr.ht.
2. Entre com sua conta.
3. Adicione uma rede.
4. Use Libera Chat ou informe outro servidor.
5. Registre seu nick na rede.
6. Configure SASL.
7. Entre nos canais.

Cliente IRC próprio

Gere um token com o grant indicado pelo link oficial do chat. Configure:

Servidor: chat.sr.ht
Porta: 6697
TLS: sim
SASL: sim
Usuário: SEU_USUARIO
Senha: TOKEN_PESSOAL

Prefira cliente com suporte às extensões do Soju. Sem suporte, configure uma entrada por rede:

SEU_USUARIO/liberachat

Com múltiplos dispositivos:

SEU_USUARIO/liberachat@desktop
SEU_USUARIO/liberachat@android

BouncerServ

Ajuda:

/msg BouncerServ help

Adicionar rede:

/msg BouncerServ network create -addr irc.example.org

Separar-se visualmente sem sair

/part detach

O bouncer continua no canal e pode preservar histórico. Para buscar as últimas 100 mensagens, clientes IRCv3 podem usar:

/quote CHATHISTORY LATEST #canal * 100

O token usado como senha do bouncer deve ser exclusivo e revogável.

23. Automatizar tarefas com o cliente oficial hut

O hut é o cliente de linha de comando mantido para SourceHut. Ele não substitui Git, SSH nem e-mail. Sua função é administrar os recursos que ficam ao redor do repositório: projetos, trackers, listas, builds, páginas, pastes, chaves, tokens e webhooks.

Para quem alterna entre vários computadores, hut economiza bastante tempo e também permite criar rotinas reproduzíveis.

23.1 Instalar

No Fedora:

sudo dnf install hut

No Debian ou Ubuntu, quando o pacote estiver disponível na versão usada:

sudo apt update
sudo apt install hut

No Arch Linux:

sudo pacman -S hut

No Windows, o caminho menos trabalhoso é usar hut dentro do WSL, no mesmo ambiente em que Git, SSH e git send-email estarão configurados. Há também binários e instruções de compilação no repositório oficial. Confirme a versão:

hut version

23.2 Criar um token e inicializar

Execute:

hut init

O assistente indica a página em meta.sr.ht na qual você cria um token OAuth2 pessoal. Conceda somente os acessos necessários. Algumas operações de resolução de nomes precisam também do grant PROFILE:RO do serviço correspondente.

O arquivo padrão fica em:

Linux e outros Unix: ~/.config/hut/config
macOS: ~/Library/Application Support/hut/config

Teste:

hut meta show
hut git list

Segurança: o token é equivalente a uma senha para as permissões concedidas. Não o coloque no repositório, não o cole em capturas de tela e não reutilize o token do Soju. Revogue imediatamente qualquer token exposto.

23.3 Evitar o token em texto simples

O arquivo de configuração aceita access-token-cmd: um comando que devolve o token na primeira linha da saída. Com o gerenciador pass, por exemplo:

instance "sourcehut" {
    origin "sr.ht"
    access-token-cmd pass sourcehut/hut
}

Cadastre o segredo antes:

pass insert sourcehut/hut

Isso não elimina a necessidade de proteger sua sessão, mas evita manter o token literal no arquivo. Se preferir o arquivo normal, limite sua leitura:

chmod 600 ~/.config/hut/config

23.4 Criar e consultar repositórios

Criar um repositório público e já cloná-lo:

hut git create meu-projeto \
  --description "Descrição curta e específica" \
  --visibility public \
  --clone

Listar, examinar e abrir um repositório no navegador:

hut git list
hut git show meu-projeto
hut git show meu-projeto --web

Atualizar descrição e branch principal:

hut git update meu-projeto \
  --description "Nova descrição" \
  --default-branch main

Alterar a visibilidade:

hut git update meu-projeto --visibility private

Adicionar acesso de leitura e escrita a outro usuário:

hut git acl update outro_usuario --repo meu-projeto --mode RW
hut git acl list meu-projeto

Antes de excluir, confirme o alvo duas vezes. A forma sem confirmação existe, mas não deve virar hábito:

hut git delete meu-projeto

23.5 Criar a estrutura de um projeto

hut hub create meu-projeto \
  --description "Aplicação de exemplo" \
  --tags "python,cli" \
  --visibility public

hut todo create meu-projeto --visibility public
hut lists create meu-projeto-devel --visibility public

hut hub link meu-projeto --gitrepo meu-projeto
hut hub link meu-projeto --tracker meu-projeto
hut hub link meu-projeto --list meu-projeto-devel

Cada hub link liga um recurso por vez. Confira:

hut hub show meu-projeto

Para usar um repositório como README extenso da página do projeto:

hut hub update meu-projeto --readme meu-projeto

23.6 Administrar tickets

Dentro de um repositório com .hut.scfg, o tracker pode ser inferido. Fora dele, selecione-o com --tracker:

hut todo ticket create --tracker meu-projeto

O editor configurado em $EDITOR será aberto para título e descrição. Também é possível alimentar o comando pela entrada padrão:

printf '%s\n\n%s\n' \
  'Documentar instalação no Fedora' \
  'Adicionar passos para dnf, venv e teste.' |
  hut todo ticket create --tracker meu-projeto

Operações comuns:

hut todo ticket list --tracker meu-projeto
hut todo ticket show 1 --tracker meu-projeto --web
hut todo ticket comment 1 --tracker meu-projeto
hut todo ticket assign 1 --tracker meu-projeto --user SEU_USUARIO
hut todo ticket update-status 1 --tracker meu-projeto \
  --status RESOLVED --resolution FIXED

Crie rótulos com cores de bom contraste:

hut todo label create bug --tracker meu-projeto --background ffdddd
hut todo label create docs --tracker meu-projeto --background dcecff
hut todo ticket label 1 --tracker meu-projeto --label docs

Use hut todo ticket show 1 antes de comentar ou fechar. IDs são locais ao tracker, portanto o ticket 1 pode existir em vários trackers.

23.7 Trabalhar com listas e patchsets

hut lists subscribe meu-projeto-devel
hut lists subscriptions
hut lists patchset list meu-projeto-devel
hut lists patchset show 123
hut lists patchset apply 123

patchset apply executa a aplicação no repositório Git local. Faça isso com a árvore limpa:

git status --short
hut lists patchset apply 123
git log --oneline --decorate -5
git diff HEAD~1

Depois dos testes, atualize o estado do patchset conforme o processo do projeto:

hut lists patchset update 123 --status APPLIED

Para guardar uma cópia local de uma lista:

hut lists archive meu-projeto-devel > meu-projeto-devel.mbox

23.8 Controlar builds

Descobrir e enviar os manifests do repositório atual:

hut builds submit --follow

Enviar um arquivo específico, com identificação:

hut builds submit .build.yml \
  --follow \
  --note "teste antes de enviar a série v2" \
  --tags "meu-projeto/test"

Consultar e depurar:

hut builds list --count 10
hut builds show
hut builds show 12345 --web
hut builds ssh 12345
hut builds artifacts 12345
hut builds resubmit 12345 --edit --follow

O SSH só funciona enquanto o job está em execução e quando a configuração do job permite a conexão. Não use o ambiente como servidor permanente: ele é efêmero.

23.9 Publicar páginas e pastes

Publicar uma pasta já gerada:

hut pages publish public --domain SEU_USUARIO.srht.site

Publicar apenas um subdiretório:

hut pages publish docs \
  --domain SEU_USUARIO.srht.site \
  --subdirectory manual

Com configurações de cache e página 404:

hut pages publish public \
  --domain SEU_USUARIO.srht.site \
  --site-config SiteConfig

Criar um paste privado a partir de um arquivo:

hut paste create diagnostico.txt --visibility private
hut paste list

Criar pela entrada padrão:

git diff | hut paste create --name alteracoes.diff --visibility unlisted

23.10 Configuração local do projeto

Na raiz do repositório, crie .hut.scfg:

tracker https://todo.sr.ht/~SEU_USUARIO/meu-projeto
development-mailing-list ~SEU_USUARIO/meu-projeto-devel@lists.sr.ht
patch-prefix true

Depois:

hut git setup
git config --get sendemail.to

Isso configura o destino padrão de git send-email. Com patch-prefix true, as séries recebem o nome do repositório no prefixo, o que ajuda listas que recebem patches de vários projetos. Versione .hut.scfg: ela contém metadados públicos do fluxo, não o token.

23.11 Backup e migração com hut

Exporte os dados da conta para uma pasta nova:

hut export backup-sourcehut-2026-07-25

Também é possível limitar a exportação:

hut export backup-tickets todo.sr.ht
hut export backup-projeto todo.sr.ht/~SEU_USUARIO/meu-projeto

Inspecione a pasta e guarde-a criptografada. A importação é uma operação que cria dados; teste primeiro com recursos pequenos e leia a ajuda da versão instalada:

hut help import
hut import DIRETORIO

23.12 Autocompletar comandos

Bash:

mkdir -p ~/.local/share/bash-completion/completions
hut completion bash > ~/.local/share/bash-completion/completions/hut

PowerShell:

New-Item -ItemType Directory -Force "$HOME\Documents\PowerShell" | Out-Null
hut completion powershell |
  Out-File -Encoding utf8 "$HOME\Documents\PowerShell\hut-completion.ps1"
Add-Content $PROFILE '. "$HOME\Documents\PowerShell\hut-completion.ps1"'

Abra um novo terminal depois. Se a política do PowerShell bloquear o arquivo, avalie a origem antes de alterar a política de execução.

24. API GraphQL e webhooks

Você não precisa da API para usar o SourceHut. Ela se torna útil quando uma tarefa repetitiva não existe no hut, quando você quer gerar relatórios ou quando outro sistema precisa reagir a eventos.

24.1 Aprender sem adivinhar a API

A documentação GraphQL é gerada a partir do esquema atual em docs.sourcehut.org. Cada serviço tem tipos, consultas, mutações e permissões próprios. O caminho seguro é:

1. escolher o serviço, como meta, git, todo ou builds;
2. localizar no esquema o tipo e os campos desejados;
3. criar um token com o menor conjunto de grants;
4. testar primeiro uma consulta de leitura;
5. somente depois escrever uma mutação;
6. tratar erros e paginação no programa.

24.2 Executar GraphQL por hut

Consulta simples:

hut graphql meta <<'EOF'
query {
  me {
    canonicalName
  }
}
EOF

Com variável:

hut graphql meta -v username=SEU_USUARIO <<'EOF'
query($username: String!) {
  userByName(username: $username) {
    canonicalName
    bio
  }
}
EOF

Para formatar a resposta:

hut graphql meta <<'EOF' | jq
query {
  me {
    canonicalName
    email
  }
}
EOF

hut --debug mostra a requisição subjacente em stderr. Use apenas em um terminal privado e revise a saída antes de compartilhá-la.

24.3 Webhooks

Webhooks evitam consultar o serviço a cada poucos segundos. Exemplos de eventos:

• criação, atualização e remoção de repositórios;
• GIT_PRE_RECEIVE e GIT_POST_RECEIVE;
• ticket criado, alterado ou resolvido;
• e-mail ou patchset recebido por uma lista;
• job de build criado;
• site publicado;
• chave SSH adicionada ou removida.

Exemplo conceitual para um webhook de repositório:

hut git webhook create meu-projeto \
  --events GIT_POST_RECEIVE \
  --url https://automacao.example.net/sourcehut

O endpoint deve:

1. aceitar HTTPS;
2. validar a origem ou assinatura conforme a modalidade documentada;
3. limitar tamanho e tempo de processamento;
4. registrar apenas metadados necessários;
5. responder rapidamente e enfileirar o trabalho demorado;
6. ser idempotente, pois entregas podem se repetir;
7. nunca executar campos recebidos como comandos de shell.

Consulte hut help SERVICO webhook create e o esquema atual antes de implantar, porque eventos e payloads variam por serviço. Durante os testes, use um endpoint próprio e descarte dados sensíveis.

24.4 Ser um bom consumidor

Prefira webhooks e paginação. Faça cache do que não muda. Identifique seu cliente com um User-Agent honesto. Não baixe repetidamente todos os repositórios ou arquivos. A documentação de git.sr.ht pede que operações em massa sejam moderadas, em geral não mais frequentes que uma vez por minuto. Isso é ainda mais importante em períodos de carga ou ataques de crawlers.

25. Projeto guiado: publicar hello-srht do início ao fim

Este exercício une as peças sem depender de um framework. Ao terminar, você terá repositório, página de projeto, tracker, lista, build e site.

Substitua SEU_USUARIO em todos os exemplos.

Etapa 1: conferir o ambiente

git --version
ssh -T git@git.sr.ht
hut version
hut meta show

Resultado esperado:

• Git responde com uma versão;
• SSH autentica sua conta, mesmo que informe ausência de shell;
• hut responde com uma versão;
• seu perfil aparece sem erro de autorização.

Etapa 2: criar o conjunto de recursos

hut git create hello-srht \
  --description "Projeto didático para aprender SourceHut" \
  --visibility public \
  --clone

hut hub create hello-srht \
  --description "Exemplo completo de um projeto no SourceHut" \
  --tags "tutorial,html" \
  --visibility public

hut todo create hello-srht --visibility public
printf '%s\n' 'Desenvolvimento e revisão do projeto hello-srht.' |
  hut lists create hello-srht-devel --visibility public

hut hub link hello-srht --gitrepo hello-srht
hut hub link hello-srht --tracker hello-srht
hut hub link hello-srht --list hello-srht-devel

Entre na pasta clonada:

cd hello-srht

Etapa 3: criar os arquivos

Crie index.html:

<!doctype html>
<html lang="pt-BR">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Hello SourceHut</title>
    <style>
      body {
        max-width: 48rem;
        margin: 4rem auto;
        padding: 0 1rem;
        font: 1.1rem/1.6 system-ui, sans-serif;
      }
    </style>
  </head>
  <body>
    <h1>Hello, SourceHut!</h1>
    <p>Repositório, build e publicação funcionando.</p>
  </body>
</html>

Crie README.md:

# hello-srht

Projeto mínimo usado para aprender o fluxo completo do SourceHut.

## Teste local

Abra `index.html` no navegador.

## Desenvolvimento

Patches: ~SEU_USUARIO/hello-srht-devel@lists.sr.ht
Tickets: https://todo.sr.ht/~SEU_USUARIO/hello-srht

Crie .hut.scfg:

tracker https://todo.sr.ht/~SEU_USUARIO/hello-srht
development-mailing-list ~SEU_USUARIO/hello-srht-devel@lists.sr.ht
patch-prefix true

Crie .build.yml:

image: alpine/latest
oauth: pages.sr.ht/PAGES:RW
packages:
  - hut
sources:
  - git@git.sr.ht:~SEU_USUARIO/hello-srht
environment:
  site: SEU_USUARIO.srht.site
tasks:
  - validar: |
      cd hello-srht
      test -s index.html
      grep -q '<h1>' index.html
  - publicar: |
      cd hello-srht
      mkdir public
      cp index.html public/
      hut pages publish -d "$site" public

Esse manifest pede apenas a permissão PAGES:RW por OAuth. O job clona o repositório, realiza duas verificações mínimas e publica a pasta public.

Etapa 4: primeiro commit e push

git add index.html README.md .hut.scfg .build.yml
git commit -m "Initial project setup"
git branch -M main
git push -u origin main

Abra o repositório:

hut git show --web

Confirme:

• os quatro arquivos aparecem;
• main é a branch principal;
• o README foi renderizado;
• o commit tem seu nome e e-mail corretos.

Se a página indicar outra branch como padrão:

hut git update hello-srht --default-branch main

Etapa 5: abrir e resolver um ticket

printf '%s\n\n%s\n' \
  'Adicionar idioma ao elemento HTML' \
  'Confirmar que lang="pt-BR" está presente.' |
  hut todo ticket create

hut todo ticket list

Se o ticket criado for o número 1, faça um commit relacionado:

git commit --allow-empty \
  -m "Document the page language" \
  -m "Refs: https://todo.sr.ht/~SEU_USUARIO/hello-srht/1"
git push

Depois de verificar o resultado:

hut todo ticket update-status 1 \
  --status RESOLVED \
  --resolution FIXED

O trailer com URL cria uma ligação compreensível entre histórico e ticket. Feche o ticket conscientemente; não dependa de palavras mágicas sem conferir o estado final.

Etapa 6: executar o build manualmente

Antes de confiar no trigger:

hut builds submit .build.yml \
  --note "primeira validação do hello-srht" \
  --follow

No log, confirme:

1. imagem Alpine iniciada;
2. repositório clonado;
3. tarefa validar concluída;
4. publicação autorizada;
5. job encerrado com sucesso.

Abra:

https://SEU_USUARIO.srht.site/

Se o build não tiver autorização para Pages, confira a linha oauth e reenvie. O build solicita grants definidos no manifest; a primeira utilização pode exigir consentimento.

Etapa 7: habilitar o trigger

Na página de configuração do repositório, adicione um trigger de builds.sr.ht para .build.yml. Faça uma mudança real:

git switch -c melhora-texto

Edite o parágrafo de index.html, então:

git add index.html
git commit -s -m "Improve the introductory text"
git push -u origin melhora-texto

Confira se o build foi criado. Para um projeto pessoal, você pode mesclar a branch:

git switch main
git merge --ff-only melhora-texto
git push

Em um projeto alheio, não faça push na branch principal. Envie patches pelo fluxo da lista.

Etapa 8: simular uma contribuição por e-mail

Configure o repositório:

hut git setup
git config --get sendemail.to

Crie uma mudança pequena em uma branch:

git switch -c docs-exemplo

Edite o README, depois:

git add README.md
git commit -s -m "Document the published site"
git format-patch --cover-letter main..HEAD

Revise todos os arquivos .patch. Primeiro faça um teste sem enviar:

git send-email --dry-run ./*.patch

Se destinatário, assunto e série estiverem corretos:

git send-email ./*.patch

Não envie a mesma série repetidamente apenas para testar. Use --dry-run e mande uma nova versão v2 somente quando houver uma alteração real.

Etapa 9: checklist de conclusão

• O perfil abre em meta.sr.ht.
• A autenticação SSH funciona.
• O repositório tem main, README e descrição.
• O projeto do hub.sr.ht mostra repositório, tracker e lista.
• O ticket de teste foi criado, ligado a um commit e resolvido.
• O build manual terminou com sucesso.
• Um push novo dispara o build esperado.
• O site abre por HTTPS.
• .hut.scfg configura o destino de patches.
• git send-email --dry-run apresenta destinatário e assuntos corretos.
• Nenhum token, senha ou segredo foi versionado.

26. Rotinas de trabalho que evitam confusão

Rotina diária de quem mantém o projeto

1. Leia os novos e-mails da lista e os tickets.

2. Atualize a cópia local:

   git switch main
   git pull --ff-only
   

3. Trabalhe em uma branch curta.

4. Faça commits pequenos, com mensagem no imperativo.

5. Rode os testes locais.

6. Envie o branch ou a série de patches conforme o fluxo escolhido.

7. Acompanhe o build.

8. Responda revisões no mesmo thread.

9. Atualize ticket e patchset somente depois da verificação.

Rotina de quem contribui

1. Leia README, CONTRIBUTING, lista e tickets.
2. Confira se alguém já está trabalhando no problema.
3. Clone o repositório e crie uma branch.
4. Faça uma mudança focada.
5. Rode testes e linters documentados pelo projeto.
6. Use git diff --check.
7. Faça commit com -s se o projeto exigir Signed-off-by.
8. Gere e revise os patches.
9. Envie à lista certa.
10. Responda às revisões e prepare v2, sem apagar a discussão anterior.

Rotina mensal de segurança e continuidade

1. Abra o audit log da conta.
2. Remova chaves SSH de máquinas que não existem mais.
3. Revogue tokens sem uso ou com escopo excessivo.
4. Exporte tickets, listas e demais metadados com hut export.
5. Faça clone espelho dos repositórios importantes.
6. Teste a leitura do backup.
7. Confira o estado dos builds e dos domínios publicados.
8. Atualize hut, Git, SSH e o cliente de e-mail.

27. Backup de verdade

Git é distribuído, mas um clone comum não preserva tudo. Ele não contém tickets, listas, configurações do projeto, chaves da conta nem necessariamente todas as referências remotas.

27.1 Espelho do repositório

git clone --mirror \
  git@git.sr.ht:~SEU_USUARIO/meu-projeto \
  meu-projeto.git

Atualizar:

git -C meu-projeto.git remote update --prune

Restaurar em outro servidor Git:

git -C meu-projeto.git push --mirror NOVA_URL

--mirror pode sobrescrever referências no destino. Use somente em um repositório vazio ou conscientemente preparado para restauração.

27.2 Dados fora do Git

Use hut export para os objetos dos serviços. Salve separadamente:

• exportação do hut;
• arquivo mbox das listas importantes;
• configuração DNS dos domínios;
• SiteConfig;
• manifests de build, já versionados;
• cópia das chaves públicas;
• registro seguro de como recuperar o e-mail e o segundo fator.

Nunca guarde a chave SSH privada ou tokens junto a uma cópia pública do repositório. Criptografe o backup e teste a restauração em uma pasta temporária.

28. Diagnóstico dos problemas mais comuns

Permission denied (publickey)

1. Rode ssh -vT git@git.sr.ht.
2. Procure a linha que informa qual chave está sendo oferecida.
3. Compare a chave pública local com a cadastrada em meta.sr.ht.
4. Carregue a chave no agente.
5. Se houver várias chaves, configure IdentityFile e IdentitiesOnly yes em ~/.ssh/config.
6. Confirme que a URL usa git@git.sr.ht, não seu nome como usuário SSH.

Repository not found

Confira:

• o til antes do proprietário: ~usuario/repositorio;
• maiúsculas, hífens e nome exato;
• se a conta recebeu acesso ao repositório privado;
• se o remote está correto:

git remote -v
hut git show ~DONO/REPOSITORIO

src refspec main does not match any

Normalmente não existe commit ou a branch tem outro nome:

git status
git branch --show-current
git log --oneline -1

Crie o primeiro commit, renomeie a branch se necessário e tente novamente:

git branch -M main
git push -u origin main

Um push foi rejeitado

Não force imediatamente. Atualize as referências e entenda a divergência:

git fetch origin
git log --oneline --graph --decorate --all -20

Se seu branch deve ficar sobre o remoto:

git rebase origin/main
git push

Se você já havia publicado o branch e precisou reescrever seu próprio histórico:

git push --force-with-lease

--force-with-lease ainda é destrutivo, porém impede sobrescrever mudanças remotas que você não viu. Não o use em branch compartilhada sem combinar.

Build não dispara

Verifique:

1. o manifest está em .build.yml, .build.yaml ou .builds/*.yml;
2. o arquivo foi enviado à branch observada;
3. o trigger está cadastrado no repositório correto;
4. YAML está válido;
5. a conta tem acesso ao serviço de builds;
6. o status geral do SourceHut não indica incidente.

Isole trigger de manifest com:

hut builds submit .build.yml --follow

Se o envio manual funciona, investigue o trigger. Se falha também, investigue o manifest e o ambiente.

Uma tarefa do build “perdeu” cd ou variável

Cada entrada de tasks é executada em uma sessão separada. Faça o cd em cada tarefa ou concentre comandos dependentes no mesmo bloco:

tasks:
  - teste: |
      cd meu-projeto
      npm ci
      npm test

Para compartilhar valores, grave-os em arquivo no diretório de trabalho ou use environment quando o valor for conhecido antes do job.

Segredo funciona no push, mas não em patch externo

Isso costuma ser intencional. Builds disparados por contribuições de terceiros não devem receber automaticamente seus segredos. Separe:

• testes sem segredo para todo patch;
• publicação apenas após revisão e merge em branch confiável;
• credenciais com escopo mínimo e validade curta.

Nunca “resolva” incorporando o segredo no YAML.

E-mail chega como HTML ou patch quebrado

Use git send-email, que envia texto sem o cliente alterar espaços e linhas. Confira também:

• editor não converteu tabs;
• servidor não anexou assinatura;
• assunto preserva [PATCH];
• série está no mesmo thread;
• mensagem não excedeu limites da lista.

Baixe o e-mail bruto ou o arquivo mbox e teste:

git am --show-current-patch=diff
git am --abort

SMTP recusa a autenticação

Confirme host, porta, TLS e política atual do provedor. Gmail normalmente requer senha de aplicativo quando 2FA está ativo. Microsoft pode exigir OAuth2 em vez de senha SMTP comum. Não desative 2FA para fazer o envio funcionar. Teste primeiro com git send-email --dry-run, lembrando que ele não valida toda a autenticação até uma transmissão real.

O patch não aplica

git am --abort
git fetch origin
git switch main
git pull --ff-only

Peça ao autor uma nova versão baseada no commit atual ou aplique em uma branch de teste e resolva conflitos conscientemente. Não esconda uma resolução significativa: explique-a na revisão.

Site abre sem CSS, fonte ou imagem

Verifique:

• caminhos absolutos que deveriam ser relativos;
• diferença entre maiúsculas e minúsculas;
• arquivos realmente presentes na pasta publicada;
• conteúdo externo servido por HTTP em uma página HTTPS;
• política CSP do srht.site;
• subdiretório usado em hut pages publish;
• base URL configurada no gerador estático.

Teste o pacote antes:

find public -maxdepth 3 -type f | sort
python3 -m http.server --directory public 8000

Repositório existe, mas o projeto parece incompleto

Um repositório em git.sr.ht não cria automaticamente a página agregadora do hub.sr.ht. Crie o projeto e ligue os recursos. Também confira se as visibilidades são compatíveis: um projeto público não torna um repositório privado acessível.

Interface ou clone estão lentos

Consulte status.sr.ht. Em períodos de abuso por crawlers, serviços públicos podem sofrer degradação. Evite repetir requests em loops, autentique operações quando possível e aguarde a normalização antes de alterar configurações que já funcionavam.

29. Folha de consulta rápida

URLs que vale memorizar

Conta:        https://meta.sr.ht/
Repositórios:https://git.sr.ht/
Projetos:     https://sr.ht/
Tickets:      https://todo.sr.ht/
Listas:       https://lists.sr.ht/
Builds:       https://builds.sr.ht/
Pastes:       https://paste.sr.ht/
Chat:         https://chat.sr.ht/
Manual:       https://man.sr.ht/
API:          https://docs.sourcehut.org/
Status:       https://status.sr.ht/

30. Glossário essencial

ACL: lista de controle de acesso. Define quem pode ler, escrever, publicar ou administrar um recurso.

Artifact: arquivo produzido por um build, como pacote, binário ou relatório.

Branch: linha de desenvolvimento dentro de um repositório Git.

Build manifest: arquivo YAML que descreve imagem, pacotes, fontes, tarefas, segredos, ambiente e artefatos de um job.

Commit: unidade de mudança versionada, identificada por hash.

Grant: permissão específica concedida a um token ou job, como PAGES:RW.

Hub project: página agregadora que apresenta repositórios, tracker, listas, site, tags e README de um projeto.

Patch: representação textual de uma mudança. Pode ser revisada e aplicada sem acesso de escrita ao repositório.

Patchset: uma ou mais mensagens de patch reconhecidas e agrupadas pela lista.

Personal access token: credencial revogável usada por ferramentas e API.

Repository: banco de objetos e referências Git. É o código e seu histórico, não o projeto inteiro.

Signed-off-by: trailer de commit que registra a declaração exigida pelo Developer Certificate of Origin quando o projeto adota esse processo. Não é uma assinatura criptográfica.

Soju: bouncer IRC usado por chat.sr.ht para manter conexões e histórico.

Tracker: quadro de tickets do todo.sr.ht.

Trigger: ligação que inicia um build após um evento, como um push.

Visibilidade pública: recurso listado e acessível publicamente.

Visibilidade não listada: acessível por URL, mas não promovido em listagens. Não deve ser tratada como proteção de segredo.

Visibilidade privada: exige autorização explícita.

Recomendações práticas

Para aprender sem se perder, use esta ordem:

1. Domine conta, SSH e Git. Faça clone, commit, push e pull sem depender de hut.
2. Crie um projeto pequeno. Use um repositório, um tracker e uma lista.
3. Aprenda patches em ambiente de teste. Gere, revise e faça --dry-run antes do primeiro envio real.
4. Adicione build somente depois do teste local. Comece com um único sistema, sem secrets e sem publicação.
5. Separe teste de implantação. Patches externos testam; apenas branches confiáveis publicam.
6. Use hut para repetição, não para esconder conceitos. Entenda o que o comando administra.
7. Faça backup de Git e dos metadados. Clone espelho mais hut export.
8. Trate e-mail como parte do projeto. Assuntos, threads e respostas são histórico técnico.
9. Prefira links completos para tickets. Evita ambiguidade entre trackers.
10. Leia o arquivo de contribuição de cada projeto. O fluxo do SourceHut é flexível; a convenção do mantenedor prevalece.

Um conjunto inicial sensato para um projeto pessoal:

• repositório público;
• README.md, LICENSE e .hut.scfg;
• projeto no hub.sr.ht;
• tracker com rótulos bug, docs e enhancement;
• lista nome-devel;
• .build.yml que apenas testa;
• publicação em srht.site somente a partir de main;
• exportação mensal e clone espelho.

Conclusão

SourceHut fica muito mais simples quando você para de compará-lo tela por tela com GitHub ou GitLab. O centro é o Git; hub.sr.ht organiza a apresentação; todo.sr.ht registra trabalho; lists.sr.ht transforma e-mail em revisão técnica arquivável; builds.sr.ht executa ambientes declarativos; pages.sr.ht publica conteúdo estático; e hut conecta tudo à linha de comando.

Você não precisa aprender todos os serviços ao mesmo tempo. Comece pelo caminho completo do projeto hello-srht: autenticar, criar, publicar, abrir um ticket, rodar um build e fazer um patch de teste. Depois disso, os recursos avançados deixam de parecer peças soltas.

O principal cuidado é operacional: use chaves e tokens separados, leia o processo de contribuição, revise cada patch antes do envio, não entregue segredos a builds de terceiros e mantenha backups dos dados que não moram no Git. Seguindo essas práticas, o SourceHut se torna uma plataforma enxuta, auditável e muito competente para projetos pessoais e colaborativos.

Fontes consultadas

• Manual oficial do SourceHut
• Tutorial oficial: configurar conta e Git
• Tutorial oficial: organizar projetos
• Tutorial oficial: primeiros passos com builds
• Documentação oficial do git.sr.ht
• Pesquisa de código no git.sr.ht
• Documentação oficial do meta.sr.ht
• Documentação oficial do hub.sr.ht
• Documentação oficial do todo.sr.ht
• Documentação oficial do lists.sr.ht
• Etiqueta das listas do SourceHut
• Documentação oficial do builds.sr.ht
• Referência oficial dos manifests de build
• Triggers do builds.sr.ht
• Repositórios privados em builds
• Tutorial oficial: secrets de build
• Início rápido do pages.sr.ht
• Automatizar publicação no pages.sr.ht
• Domínios personalizados no pages.sr.ht
• Permissões no pages.sr.ht
• Configurações avançadas do pages.sr.ht
• Limitações do pages.sr.ht
• Documentação oficial do paste.sr.ht
• Documentação oficial do chat.sr.ht
• Uso do Soju no chat.sr.ht
• Documentação GraphQL atual do SourceHut
• Repositório e manual do hut
• Guia prático do git send-email
• Guia prático do git am
• Guia prático do git rebase
• Planos e condições atuais do SourceHut
• Status operacional dos serviços

Nota sobre atualidade

Pesquisa concluída em 25 de julho de 2026. O SourceHut continua em fase alpha e seus serviços, preços, permissões, formatos de manifest e comandos podem mudar. Confirme procedimentos sensíveis no manual oficial e no esquema GraphQL atual antes de automatizar produção, configurar faturamento ou conceder acesso a dados privados.