Tutorials — GiTide

Install and set up a repositoryInstalar e configurar um repositório

This takes about five minutes and leaves you with a gtide program and a repository that shares one set of rules.

Leva uns cinco minutos e termina com o programa gtide e um repositório com um conjunto único de regras.

Check the requirementsConfira os requisitos
You need Git 2.30 or newer, on macOS, Linux or Windows. You do not need Go to use a release. On Windows, install Git for Windows: the installed hooks are shell scripts, which it runs with its bundled shell.

Você precisa de Git 2.30 ou mais novo, no macOS, Linux ou Windows. Não precisa do Go para usar uma release. No Windows, instale o Git for Windows: os hooks instalados são scripts shell, que ele executa com o shell que o acompanha.
```
$ git --version
```
Install itInstale
Run one command. It picks the right file for your system, checks it against checksums.txt, and installs gtide plus the optional tide alias (never over a different program called tide). On macOS and Linux:

Execute um comando. Ele escolhe o arquivo certo para o seu sistema, confere com o checksums.txt e instala o gtide mais o alias opcional tide (nunca por cima de outro programa chamado tide). No macOS e no Linux:
```
$ curl -fsSL https://github.com/Cellestias/git-tide/releases/latest/download/install.sh | sh
Checksum OK
$ gtide --version
gtide version v1.2.0
```
On Windows, in PowerShell (open a new terminal afterwards so the new PATH applies):

No Windows, no PowerShell (abra um novo terminal depois para o novo PATH valer):
```
PS> irm https://github.com/Cellestias/git-tide/releases/latest/download/install.ps1 | iex
```
Options are environment variables: GTIDE_VERSION=v1.2.0 to pick a release, GTIDE_BIN_DIR (GTIDE_INSTALL_DIR on Windows) to choose the folder, and GTIDE_NO_ALIAS=1 to skip tide. You can also download a file from the download section or the Releases page. If a browser-downloaded file is blocked, macOS needs xattr -d com.apple.quarantine gtide once and Windows SmartScreen needs More info, Run anyway. To build from source instead, clone the repository and run make install (needs Go 1.26.10 or newer).

As opções são variáveis de ambiente: GTIDE_VERSION=v1.2.0 para escolher a release, GTIDE_BIN_DIR (GTIDE_INSTALL_DIR no Windows) para escolher a pasta e GTIDE_NO_ALIAS=1 para pular o tide. Você também pode baixar um arquivo na seção de download ou na página de Releases. Se um arquivo baixado pelo navegador for bloqueado, o macOS pede xattr -d com.apple.quarantine gtide uma vez e o SmartScreen do Windows pede Mais informações, Executar assim mesmo. Para compilar do código-fonte, clone o repositório e execute make install (precisa do Go 1.26.10 ou mais novo).

Heads upAtenção
The binary must be on the PATH that Git sees, because the installed hooks call gtide. If it is missing, the hooks print a warning and skip their checks. GUI clients and IDEs often do not inherit your terminal’s PATH.

O binário precisa estar no PATH que o Git enxerga, porque os hooks instalados chamam o gtide. Se ele faltar, os hooks mostram um aviso e pulam as verificações. Clientes gráficos e IDEs muitas vezes não herdam o PATH do terminal.
Set up your repositoryConfigure o seu repositório
Inside the repository, run gtide init. It creates .tide.yml and installs three Git hooks. Then run gtide doctor to check everything.

Dentro do repositório, execute gtide init. Ele cria o .tide.yml e instala três hooks do Git. Depois execute gtide doctor para conferir tudo.
```
$ cd your-repo
$ gtide init
✓ hook pre-commit: installed
✓ hook commit-msg: installed
✓ hook pre-push: installed
✓ created /home/dev/tool/.tide.yml (base branch: main)
$ gtide doctor
✓ git: git version 2.45.1
✓ repository: /home/dev/tool
✓ config: /home/dev/tool/.tide.yml
✓ remote: origin → acme/tool
✓ base branch: main
✓ pre-commit: installed
✓ commit-msg: installed
✓ pre-push: installed
✓ gtide on PATH: found
```
The base branch is detected from origin/HEAD, then main, then master. Override it with gtide init --base stage.

A branch base é detectada a partir de origin/HEAD, depois main, depois master. Troque-a com gtide init --base stage.
Share the rules with your teamCompartilhe as regras com o time
Commit .tide.yml so everyone works with the same base branches, protected branches and conventions. Your first commit already goes through the hooks, so it must be a Conventional Commit.

Commite o .tide.yml para que todos usem as mesmas branches base, branches protegidas e convenções. O seu primeiro commit já passa pelos hooks, então precisa ser um Conventional Commit.
```
$ git add .tide.yml
$ git commit -m "chore: add gtide configuration"
```

A day with GiTide: from branch to Pull RequestUm dia com o GiTide: da branch à Pull Request

This is the loop you will repeat most. It assumes .tide.yml maps feature/* branches to stage.

Este é o ciclo que você mais vai repetir. Ele assume que o .tide.yml mapeia branches feature/* para stage.

Start from a fresh baseComece de uma base atualizada
gtide create fetches the base and starts your branch from origin/stage. Your local stage is not touched, and the new branch has no upstream yet.

O gtide create busca a base e inicia a sua branch em origin/stage. O seu stage local não é alterado, e a nova branch ainda não tem upstream.
```
$ gtide create feature/login
  base: stage (from .tide.yml)
→ Fetching origin/stage
✓ Created and switched to feature/login from origin/stage
```
Commit as usualFaça commits como sempre
Use plain Git. The hooks check the message format and scan the lines you added for secrets. If something is wrong, the commit is rejected with the reason.

Use o Git normal. Os hooks conferem o formato da mensagem e analisam as linhas que você adicionou em busca de secrets. Se algo estiver errado, o commit é rejeitado com o motivo.
```
$ git add src/login.go
$ git commit -m "feat: add login form"
```
Or let GiTide stage and commit in one step. It runs the same checks first (see the next tutorial).

Ou deixe o GiTide fazer stage e commit num passo só. Ele roda as mesmas verificações antes (veja o próximo tutorial).
```
$ gtide save -m "feat: add login form" -f src/login.go
→ Committed a1b2c3d on feature/login: feat: add login form (1 file)
```

Publish the branchPublique a branch

$ gtide push
→ Pushing feature/login to origin
✓ Pushed feature/login to origin and set it as upstream

Catch up with the baseAlcance a base

While you worked, stage moved. Bring it in:

Enquanto você trabalhava, o stage andou. Traga-o para a sua branch:

$ gtide update
→ Fetching origin/stage
→ Updating local stage
→ Integrating stage into feature/login (merge)
✓ Updated to include stage

Open the Pull RequestAbra a Pull Request
gtide pr shows a summary and asks before it pushes anything. It needs a GitHub token with pull-request write access (see Authenticate with GitHub).

O gtide pr mostra um resumo e pergunta antes de enviar qualquer coisa. Ele precisa de um token do GitHub com permissão de escrita em pull requests (veja Autenticar no GitHub).
```
$ export GITHUB_TOKEN=...
$ gtide pr
→ Fetching origin/stage
Pull request feature/login → stage in acme/tool
  title:   feat: add login form
  commits: 1
Push feature/login to origin and open the pull request? [y/N] y
→ Pushing feature/login to origin
→ Opening pull request
✓ Opened #124: https://github.com/acme/tool/pull/124
```
The title is the commit subject when the branch has exactly one commit, otherwise a humanised branch name (feature/login-page becomes “Login page”). The body lists the commit subjects. Override them with --title and --body, or open a draft with --draft.

O título é o assunto do commit quando a branch tem exatamente um commit; caso contrário, é o nome da branch em linguagem natural (feature/login-page vira “Login page”). O corpo lista os assuntos dos commits. Troque-os com --title e --body, ou abra um rascunho com --draft.

Commit and save with checksCommit e save com verificações

gtide commit commits what is already staged. gtide save stages and commits in one step: the files you name with -f, or every change when you give none.

O gtide commit faz commit do que já está staged. O gtide save faz stage e commit num passo só: os arquivos que você nomear com -f, ou todas as alterações se você não indicar nenhum.

$ gtide commit -m "feat(auth): add login form"
$ gtide commit --type feat --scope auth -m "add login form"   # builds "feat(auth): add login form"
$ gtide commit -a -m "fix: handle empty token"                # also stages tracked changes
$ gtide save -m "feat: add login form"                       # every change, new files included
$ gtide save -m "feat(auth): add login form" -f src/auth/login_form.tsx
$ gtide save --type fix -m "handle empty token" -f api/token.go -f api/token_test.go
$ gtide save -m "docs: update readme" -f docs/                # a directory stages everything under it

$ gtide save -m "feat: add login form"
→ staged 2 file(s): src/login.go, src/login_test.go
✓ Committed a1b2c3d on feature/login: feat: add login form (2 files)

FlagFlag	EffectEfeito
`-m, --message`	The commit message (required).A mensagem do commit (obrigatória).
`--type`, `--scope`	Build `type(scope): message` from `-m`. `--scope` needs `--type`.Monta `type(scope): message` a partir do `-m`. O `--scope` exige o `--type`.
`--body`	Commit body, after a blank line.Corpo do commit, depois de uma linha em branco.
`-a, --all`	`gtide commit` only: stage modifications and deletions of tracked files first. Untracked files are never added.Só no `gtide commit`: faz stage das modificações e remoções de arquivos rastreados antes. Arquivos não rastreados nunca são adicionados.
`-f, --file`	`gtide save` only, repeatable: stage only this file or directory. Without it, every change is staged. Paths are relative to where you run the command and must be inside the repository.Só no `gtide save`, repetível: faz stage apenas deste arquivo ou diretório. Sem ele, todas as alterações recebem stage. Os caminhos são relativos a onde você executa o comando e precisam estar dentro do repositório.

What it checks firstO que ele confere antes

Before anything is committed, GiTide checks that the branch is not protected, that the message follows your Conventional Commits rules, and that the staged lines hold no likely secrets or leftover merge conflict markers. These are the same checks as the hooks, with friendlier errors. Your Git hooks still run, and GiTide never uses --no-verify.

Antes de commitar qualquer coisa, o GiTide confere que a branch não é protegida, que a mensagem segue as suas regras de Conventional Commits e que as linhas staged não têm prováveis secrets nem marcadores de conflito esquecidos. São as mesmas verificações dos hooks, com erros mais amigáveis. Os seus hooks do Git continuam rodando, e o GiTide nunca usa --no-verify.

Good to knowBom saber

gtide save without -f is like git add --all: modified, deleted and new files that .gitignore does not exclude. GiTide lists what it staged before committing, and the secret scan covers new files too. With -f it refuses when other files are already staged, so the commit holds exactly the files you named. If a check fails after staging, GiTide restores the index and nothing stays staged. It also refuses during a merge or rebase, where plain git commit (or gtide continue) is the right tool.

O gtide save sem -f é como git add --all: arquivos modificados, removidos e novos que o .gitignore não exclui. O GiTide lista o que colocou em stage antes de commitar, e a detecção de secrets cobre os arquivos novos também. Com -f ele recusa se já houver outros arquivos em stage, para o commit conter exatamente os arquivos que você nomeou. Se uma verificação falhar depois do stage, o GiTide restaura o índice e nada fica em stage. Ele também recusa durante um merge ou rebase, onde o git commit normal (ou o gtide continue) é a ferramenta certa.

Keep a branch up to dateMantenha uma branch atualizada

gtide update brings the base branch into your current branch without risking your uncommitted work. In order, it:

O gtide update traz a branch base para a sua branch atual sem arriscar o seu trabalho não commitado. Em ordem, ele:

checks that the repository is in a safe state;
fetches the base branch from the configured remote;
fast-forwards the local base branch to match (it never creates merge commits or discards commits on the base);
integrates the base into your branch with merge (default) or rebase;
leaves you on your original branch and reports whether anything changed.

confere se o repositório está num estado seguro;
busca a branch base do remote configurado;
avança a branch base local para igualar (nunca cria commits de merge nem descarta commits da base);
integra a base na sua branch com merge (padrão) ou rebase;
deixa você na sua branch original e informa se algo mudou.

$ gtide update            # base resolved from .tide.yml
$ gtide update main       # use this base for this run only

When it stopsQuando ele para

It stops before changing anything when HEAD is detached, when tracked files have staged or unstaged changes (untracked files are fine), or when a merge, rebase, cherry-pick or revert is already in progress. It never stashes, resets or cleans for you.

Ele para antes de alterar qualquer coisa quando o HEAD está destacado, quando arquivos rastreados têm alterações staged ou não staged (arquivos não rastreados não contam) ou quando um merge, rebase, cherry-pick ou revert já está em andamento. Ele nunca faz stash, reset ou clean por você.

$ gtide update
✗ uncommitted changes would be at risk: src/login.go, README.md
  hint: commit or stash them, then re-run `gtide update`

It also stops if the local base branch has diverged from the remote, or is checked out in another worktree. Fix that branch by hand (or work on a separate branch), then re-run.

Ele também para se a branch base local divergiu do remote ou está em uso em outro worktree. Corrija essa branch à mão (ou trabalhe numa branch separada) e execute de novo.

Resolving conflictsResolvendo conflitos

On conflicts the repository is left in Git’s normal conflict state, so everything you already know applies.

Em caso de conflito, o repositório fica no estado normal de conflito do Git, então tudo o que você já sabe se aplica.

$ gtide update
→ Fetching origin/stage
→ Updating local stage
→ Integrating stage into feature/login (merge)
✗ conflicts while integrating the base branch (merge)
  hint: resolve the conflicts, git add the files, then `git merge --continue`;
        or give up with `git merge --abort`

Edit the conflicting files, git add them, then run gtide continue. It finishes the merge, rebase, cherry-pick or revert without you having to remember which one it was. Plain git merge --continue and git rebase --continue work too. To give up, run gtide abort.

Edite os arquivos em conflito, faça git add neles e execute gtide continue. Ele conclui o merge, rebase, cherry-pick ou revert sem você precisar lembrar qual era. O git merge --continue e o git rebase --continue normais também funcionam. Para desistir, execute gtide abort.

$ git add src/login.go
$ gtide continue
→ Continuing the merge
✓ Finished the merge

gtide continue refuses while any file still has conflicts, and lists them. Before continuing it runs the pre-commit checks, so a file staged with leftover <<<<<<< markers or a secret is rejected and the operation stays in progress. Git’s prepared message is used as it is, with no editor. A rebase can stop again on the next commit: resolve it and run gtide continue again.

O gtide continue recusa enquanto algum arquivo ainda tiver conflitos, e os lista. Antes de continuar ele roda as verificações de pre-commit, então um arquivo em stage com marcadores <<<<<<< esquecidos ou um secret é rejeitado e a operação continua em andamento. A mensagem preparada pelo Git é usada como está, sem editor. Um rebase pode parar de novo no commit seguinte: resolva e execute gtide continue outra vez.

$ gtide continue
✗ 1 file(s) still have conflicts: src/login.go
  hint: edit them to remove the conflict markers, then `git add <file>` and run `gtide continue` again

$ gtide abort --yes
→ Aborting the merge
✓ Aborted the merge; the branch is back to how it was

See and switch branchesVeja e troque de branch

Listing branchesListando branches

gtide branch lists branches with GiTide’s view of them. By default it uses local data only, so it works offline.

O gtide branch lista as branches com a visão do GiTide sobre elas. Por padrão usa só dados locais, então funciona offline.

$ gtide branch
BRANCH         UPDATED       LAST AUTHOR  UPSTREAM  BASE     STATUS
* feature/new  2 hours ago   Ana          in sync   main ↑2  -
  feature/old  3 months ago  Bruno        none      main ↑1  -
  fix/done     5 days ago    Ana          none      main ↓1  merged
  main         1 hour ago    Ana          in sync   -        protected

ColumnColuna	MeaningSignificado
`UPSTREAM`	Ahead (↑) and behind (↓) against the upstream, `in sync`, `none`, or `gone` when the upstream was deleted on the remote.À frente (↑) e atrás (↓) do upstream, `in sync`, `none`, ou `gone` quando o upstream foi apagado no remote.
`BASE`	The base branch from `.tide.yml` with ahead/behind against it.A branch base do `.tide.yml`, com quantos commits à frente/atrás dela.
`STATUS`	`protected` (in `.tide.yml`), `merged` (nothing the base lacks, and the base has moved on), or `remote-only`.`protected` (no `.tide.yml`), `merged` (nada que a base não tenha, e a base já avançou) ou `remote-only`.
`LAST AUTHOR`	Author of the last commit. Git does not record who created a branch, so this is the closest honest answer.Autor do último commit. O Git não registra quem criou uma branch, então esta é a resposta honesta mais próxima.

Filters combine, and every one must match. Progress messages go to stderr, so the table on stdout is safe to pipe.

Os filtros se combinam, e todos precisam casar. As mensagens de progresso vão para o stderr, então a tabela no stdout é segura para usar em pipe.

$ gtide branch --remote --github     # + remote-only branches, GitHub protection and open PRs
$ gtide branch --mine --sort name     # only branches whose last author is you
$ gtide branch --merged               # candidates for cleanup
$ gtide branch --stale 30             # no commits for more than 30 days

Switching safelyTrocando com segurança

gtide change (alias gtide switch) accepts an exact name, a case-insensitive part of a name that matches exactly one branch, or - for the previous branch. An exact name always wins over partial matches; if several branches match, GiTide lists them and refuses.

O gtide change (alias gtide switch) aceita um nome exato, uma parte do nome sem diferenciar maiúsculas que case com exatamente uma branch, ou - para a branch anterior. Um nome exato sempre vence os casamentos parciais; se várias branches casarem, o GiTide as lista e recusa.

$ gtide change two-fa
✓ Switched to feature/two-fa
  ↓2 behind stage: run `gtide update`
$ gtide change -             # previous branch
$ gtide change main --carry

A branch that only exists on the remote (already fetched) is created locally with its upstream set. It refuses, without changing anything, while a merge or rebase is in progress and when tracked files have uncommitted changes. Pass --carry to let Git bring the changes along; Git still refuses if they would conflict, and nothing is lost either way. GiTide never stashes for you.

Uma branch que só existe no remote (já buscada) é criada localmente com o upstream configurado. Ele recusa, sem alterar nada, enquanto um merge ou rebase está em andamento e quando arquivos rastreados têm alterações não commitadas. Passe --carry para o Git levar as alterações junto; o Git ainda recusa se elas entrarem em conflito, e nada se perde de qualquer forma. O GiTide nunca faz stash por você.

After switching, GiTide tells you what to do next: when the branch is behind its base (gtide update), behind its upstream (git pull), when its upstream was deleted, or when it is protected. gtide change makes no network call; refresh remote branches with gtide branch --remote.

Depois de trocar, o GiTide diz o que fazer a seguir: quando a branch está atrás da base (gtide update), atrás do upstream (git pull), quando o upstream foi apagado ou quando ela é protegida. O gtide change não faz chamadas de rede; atualize as branches remotas com gtide branch --remote.

Creating branchesCriando branches

FlagFlag	EffectEfeito
`--from <ref>`	Start from this branch, tag or commit instead of the configured base.Começa desta branch, tag ou commit em vez da base configurada.
`--local`	Start from the local branch and make no network call.Começa da branch local e não faz chamada de rede.
`--track`	The branch must already exist on the remote: create a local branch from it and set the upstream.A branch já precisa existir no remote: cria uma branch local a partir dela e configura o upstream.
`--push`	Also push the new branch and set its upstream. If the push fails, the branch still exists locally.Também envia a nova branch e configura o upstream. Se o push falhar, a branch continua existindo localmente.
`--no-switch`	Create the branch without checking it out; allowed even with uncommitted changes.Cria a branch sem fazer checkout; permitido mesmo com alterações não commitadas.

Review a Pull RequestRevise uma Pull Request

gtide review checks out a GitHub Pull Request on a predictable local branch, tide/review/pr-<number>. It fetches refs/pull/<n>/head, so it works for Pull Requests from forks too.

O gtide review baixa uma Pull Request do GitHub numa branch local previsível, tide/review/pr-<número>. Ele busca refs/pull/<n>/head, então funciona também com Pull Requests de forks.

$ gtide review 123
→ Reading acme/tool#123
→ Fetching refs/pull/123/head
✓ On review branch tide/review/pr-123
  title:  Add login form
  author: ana
  state:  open
  source: feature/login
  target: stage
  next:   git diff origin/stage...HEAD    (return with: git switch main)

Accepted forms: gtide review 123, gtide review '#123' or a full URL such as https://github.com/acme/tool/pull/123 (it must point to the configured remote’s repository). Run the suggested git diff, then return with git switch <branch>.

Formas aceitas: gtide review 123, gtide review '#123' ou uma URL completa como https://github.com/acme/tool/pull/123 (ela precisa apontar para o repositório do remote configurado). Rode o git diff sugerido e volte com git switch <branch>.

Good to knowBom saber

It needs a clean tracked working tree.
Re-running it fast-forwards the existing review branch.
If the review branch has local commits that are not in the Pull Request, GiTide refuses. Re-run with --reset to discard them.
Public repositories work without a token; private ones need GITHUB_TOKEN (or GH_TOKEN).

Exige uma working tree rastreada limpa.
Executá-lo de novo avança a branch de revisão existente.
Se a branch de revisão tiver commits locais que não estão na Pull Request, o GiTide recusa. Execute de novo com --reset para descartá-los.
Repositórios públicos funcionam sem token; os privados precisam de GITHUB_TOKEN (ou GH_TOKEN).

Authenticate with GitHubAutenticar no GitHub

gtide pr needs a GitHub token with pull-request write access: a fine-grained token with “Pull requests: Read and write” and “Contents: Read” on the repository, or a classic token with the repo scope. gtide review and gtide branch --github only need a token for private repositories. Pushing uses Git’s own authentication, not this token.

O gtide pr precisa de um token do GitHub com permissão de escrita em pull requests: um token fine-grained com “Pull requests: Read and write” e “Contents: Read” no repositório, ou um token clássico com o escopo repo. O gtide review e o gtide branch --github só precisam de token para repositórios privados. O push usa a autenticação do próprio Git, não este token.

Where GiTide looks for itOnde o GiTide procura o token

GiTide uses the first token it finds, in this order:

O GiTide usa o primeiro token que encontrar, nesta ordem:

the GITHUB_TOKEN environment variable;
the GH_TOKEN environment variable;
a GITHUB_TOKEN= or GH_TOKEN= line in the .env file at the repository root.

a variável de ambiente GITHUB_TOKEN;
a variável de ambiente GH_TOKEN;
uma linha GITHUB_TOKEN= ou GH_TOKEN= no arquivo .env na raiz do repositório.

The .env is per repository, so each project can use the token of its own organisation:

O .env é por repositório, então cada projeto pode usar o token da sua própria organização:

# <repo>/.env
GITHUB_TOKEN=ghp_xxx

$ echo ".env" >> .gitignore   # keep it out of Git

Only those two keys are read from .env; the rest of the file is ignored and nothing is exported to other processes. Quotes, export and # comments are understood; $VARIABLE is not expanded. The file must be a regular file of at most 64 KB.

Só essas duas chaves são lidas do .env; o resto do arquivo é ignorado e nada é exportado para outros processos. Aspas, export e comentários com # são entendidos; o $VARIABLE não é expandido. O arquivo precisa ser um arquivo regular de no máximo 64 KB.

Already logged in with the GitHub CLI? Reuse that login:

Já está logado com a GitHub CLI? Reaproveite esse login:

$ export GITHUB_TOKEN=$(gh auth token)

Configure .tide.ymlConfigure o .tide.yml

GiTide reads .tide.yml from the repository root. Omitted keys use defaults, and unknown keys are rejected, so typos do not pass silently. A typical team setup:

O GiTide lê o .tide.yml na raiz do repositório. Chaves omitidas usam valores padrão, e chaves desconhecidas são rejeitadas, então erros de digitação não passam em silêncio. Uma configuração típica de time:

version: 1
remote: origin

branches:
  default_base: stage
  protected:
    - main
    - stage
  base:
    feature/*: stage
    fix/*: stage
    release/*: main

update:
  strategy: merge

commits:
  convention: conventional
  require_scope: false

secrets:
  enabled: true
  custom_patterns:
    - name: internal_token
      pattern: "corp_[A-Za-z0-9]{32}"

hooks:
  manage: true

$ gtide config validate
✓ /home/dev/tool/.tide.yml is valid
$ gtide config show      # effective configuration: file merged over defaults

Choosing a base branchEscolhendo a branch base

branches.base maps a branch pattern to its base. * matches within one path segment and ** across segments. When several patterns match, the most specific wins, regardless of the order in the file: an exact name beats any pattern, and among patterns the one with more literal characters wins.

O branches.base mapeia um padrão de branch à sua base. O * casa dentro de um segmento do caminho e o ** entre segmentos. Quando vários padrões casam, o mais específico vence, independentemente da ordem no arquivo: um nome exato vence qualquer padrão e, entre padrões, vence o que tem mais caracteres literais.

branches:
  default_base: stage
  base:
    feature/*: stage
    feature/infra-*: main            # beats feature/*
    feature/hotfix-payments: main    # exact name beats both

For a one-off exception, pass the base explicitly: gtide update main or gtide pr --base main.

Para uma exceção pontual, passe a base explicitamente: gtide update main ou gtide pr --base main.

Understand the hooksEntenda os hooks

gtide init installs three hooks. They apply to every Git client on the machine, including IDEs, not only to the terminal.

O gtide init instala três hooks. Eles valem para todo cliente Git na máquina, incluindo IDEs, e não só para o terminal.

HookHook	RejectsRejeita
`pre-commit`	A commit on a protected branch, staged changes containing a likely secret, or leftover merge conflict markers.Um commit numa branch protegida, alterações staged com um provável secret, ou marcadores de conflito de merge esquecidos.
`commit-msg`	A message that is not a Conventional Commit.Uma mensagem que não é um Conventional Commit.
`pre-push`	A push that updates or deletes a protected branch on the remote.Um push que atualiza ou apaga uma branch protegida no remote.

Commit messagesMensagens de commit

A message must look like type(scope)!: description; the scope and the ! are optional (set commits.require_scope: true to require the scope). Accepted types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert. Messages Git generates itself (Merge ..., Revert "...", fixup!, squash!, amend!) are accepted.

Uma mensagem precisa ter a forma type(scope)!: description; o escopo e o ! são opcionais (defina commits.require_scope: true para exigir o escopo). Tipos aceitos: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert. Mensagens que o próprio Git gera (Merge ..., Revert "...", fixup!, squash!, amend!) são aceitas.

feat: add login form
fix(api): handle expired access tokens
refactor(core)!: drop the legacy session store

A rejection explains why and shows a valid example.

Uma rejeição explica o motivo e mostra um exemplo válido.

Secret scanningDetecção de secrets

The pre-commit hook inspects only the lines you add. Built-in detectors cover AWS access key IDs, GitHub tokens, Slack tokens, Stripe live keys, Google API keys and private key headers. Findings show the file, line and rule name, never the matched value.

O hook pre-commit analisa só as linhas que você adiciona. Os detectores embutidos cobrem IDs de chave de acesso da AWS, tokens do GitHub, tokens do Slack, chaves live da Stripe, chaves de API do Google e cabeçalhos de chave privada. Os resultados mostram o arquivo, a linha e o nome da regra, nunca o valor encontrado.

$ git commit -m "feat: add client"
✗ 1 likely secret(s) in staged changes:
  config/settings.py:14 (github_token)
  hint: remove the secret from the change; for a false positive
        add `gtide:allow-secret` to that line

For a false positive, put gtide:allow-secret on that line (in a comment, for example). To catch your own formats, add secrets.custom_patterns: each entry has a name (lowercase, digits, _, -) and a pattern (a Go regular expression), up to 100.

Para um falso positivo, coloque gtide:allow-secret naquela linha (num comentário, por exemplo). Para pegar formatos seus, adicione secrets.custom_patterns: cada entrada tem um name (minúsculas, dígitos, _, -) e um pattern (uma expressão regular do Go), até 100.

Conflict markersMarcadores de conflito

Added lines that start with <<<<<<< or >>>>>>> (what Git writes into a file on a conflict) block the commit, so an unresolved conflict cannot slip into history. This check is always on, even when secrets.enabled is false. A lone ======= is not flagged, since it is a common heading underline. For content that really contains a marker, put gtide:allow-conflict-marker on that line. gtide commit and gtide save apply the same check.

Linhas adicionadas que começam com <<<<<<< ou >>>>>>> (o que o Git escreve num arquivo em caso de conflito) bloqueiam o commit, para que um conflito não resolvido não entre no histórico. Esta verificação está sempre ativa, mesmo com secrets.enabled em false. Um ======= sozinho não é sinalizado, por ser um sublinhado de título comum. Para um conteúdo que realmente tenha um marcador, coloque gtide:allow-conflict-marker naquela linha. O gtide commit e o gtide save aplicam a mesma verificação.

Protected branchesBranches protegidas

List them in branches.protected. The hooks then stop direct commits and pushes, nudging the team to work on branches and merge through Pull Requests. Commits made while HEAD is detached (for example during a rebase) are not blocked.

Liste-as em branches.protected. Os hooks passam a barrar commits e pushes diretos, empurrando o time a trabalhar em branches e mesclar por Pull Requests. Commits feitos com o HEAD destacado (por exemplo, durante um rebase) não são bloqueados.

Bypassing and removingContornando e removendo

To bypass the hooks once, use Git’s own flag: git commit --no-verify or git push --no-verify. To remove GiTide’s hooks, delete the three files in the hooks directory (git rev-parse --git-path hooks) and, where a <hook>.pre-tide file exists, rename it back.

Para contornar os hooks uma vez, use a flag do próprio Git: git commit --no-verify ou git push --no-verify. Para remover os hooks do GiTide, apague os três arquivos do diretório de hooks (git rev-parse --git-path hooks) e, onde existir um arquivo <hook>.pre-tide, renomeie-o de volta.

TroubleshootingSolução de problemas

Hooks print “gtide: not found on PATH; skipping … checks”Os hooks imprimem “gtide: not found on PATH; skipping … checks”

Git cannot find the binary. Put gtide in a directory on the PATH that your Git client sees. GUI clients and IDEs often do not inherit the terminal’s PATH.

O Git não encontra o binário. Coloque o gtide num diretório do PATH que o seu cliente Git enxerga. Clientes gráficos e IDEs muitas vezes não herdam o PATH do terminal.

Hooks do not run at allOs hooks não rodam de jeito nenhum

Run gtide doctor. Check that core.hooksPath is not pointing elsewhere (git config core.hooksPath) and that the hook files are executable. Re-run gtide init after changing the hooks directory.

Execute o gtide doctor. Confira se o core.hooksPath não aponta para outro lugar (git config core.hooksPath) e se os arquivos de hook são executáveis. Execute o gtide init de novo depois de mudar o diretório de hooks.

gtide update: “uncommitted changes would be at risk”gtide update: “uncommitted changes would be at risk”

Commit or stash your tracked changes, then re-run. GiTide will not touch them.

Faça commit ou stash das suas alterações rastreadas e execute de novo. O GiTide não vai tocar nelas.

gtide update: “cannot fast-forward local <base>”gtide update: “cannot fast-forward local <base>”

The local base branch has commits the remote does not, or is checked out in another worktree. Fix that branch by hand (or work on a separate branch), then re-run.

A branch base local tem commits que o remote não tem, ou está em uso em outro worktree. Corrija essa branch à mão (ou trabalhe numa branch separada) e execute de novo.

A commit is rejected for a secret that is not a secretUm commit é rejeitado por um secret que não é um secret

Add gtide:allow-secret to that line, or narrow your custom pattern.

Adicione gtide:allow-secret àquela linha, ou torne o seu padrão personalizado mais específico.

gtide pr: “GITHUB_TOKEN is not set”gtide pr: “GITHUB_TOKEN is not set”

Export a token with pull-request write access, or put it in .env at the repository root (see Authenticate with GitHub). gtide review works without a token only for public repositories.

Exporte um token com permissão de escrita em pull requests, ou coloque-o no .env na raiz do repositório (veja Autenticar no GitHub). O gtide review funciona sem token só em repositórios públicos.

A warning says .env is tracked by GitUm aviso diz que o .env está rastreado pelo Git

GiTide ignored it on purpose, because the token is already exposed. Revoke the token, run git rm --cached .env, add .env to .gitignore, and create a new token.

O GiTide o ignorou de propósito, porque o token já está exposto. Revogue o token, execute git rm --cached .env, adicione o .env ao .gitignore e crie um novo token.

gtide continue: “file(s) still have conflicts”gtide continue: “file(s) still have conflicts”

Edit the listed files to remove the conflict markers, git add them, then run gtide continue again.

Edite os arquivos listados para remover os marcadores de conflito, faça git add neles e execute gtide continue de novo.

A commit is rejected for merge conflict markersUm commit é rejeitado por marcadores de conflito de merge

A staged line starts with <<<<<<< or >>>>>>>. Finish resolving the conflict, or put gtide:allow-conflict-marker on a line that really contains one.

Uma linha em stage começa com <<<<<<< ou >>>>>>>. Termine de resolver o conflito, ou coloque gtide:allow-conflict-marker numa linha que realmente contenha um.

gtide review or gtide pr: “not a supported GitHub remote”gtide review ou gtide pr: “not a supported GitHub remote”

The configured remote must be a github.com URL (HTTPS, ssh://, or [email protected]:owner/repo.git). Change remote in .tide.yml if your GitHub remote is not origin.

O remote configurado precisa ser uma URL github.com (HTTPS, ssh:// ou [email protected]:owner/repo.git). Mude o remote no .tide.yml se o seu remote do GitHub não for o origin.

ReferenceReferência

Run gtide <command> --help for the built-in help.

Execute gtide <comando> --help para a ajuda embutida.

CommandsComandos

CommandComando	What it doesO que faz	NetworkRede
`gtide init`	Create `.tide.yml` and install the hooks. Flags: `--base`, `--no-hooks`.Cria o `.tide.yml` e instala os hooks. Flags: `--base`, `--no-hooks`.	nonão
`gtide create <branch>`	Create a branch from an up-to-date base. Flags: `--from`, `--local`, `--track`, `--push`, `--no-switch`.Cria uma branch a partir de uma base atualizada. Flags: `--from`, `--local`, `--track`, `--push`, `--no-switch`.	fetch, push with `--push`fetch, push com `--push`
`gtide change <branch>`	Switch branches safely. Alias `switch`. Flag: `--carry`.Troca de branch com segurança. Alias `switch`. Flag: `--carry`.	nonão
`gtide branch`	List branches. Alias `branches`. Flags: `--remote`, `--github`, `--mine`, `--stale`, `--merged`, `--sort`.Lista branches. Alias `branches`. Flags: `--remote`, `--github`, `--mine`, `--stale`, `--merged`, `--sort`.	`--remote`, `--github--remote`, `--github`
`gtide update [branch]`	Bring the base branch into the current branch.Traz a branch base para a branch atual.	fetchfetch
`gtide commit`	Commit what is staged, after the checks. Flags: `-m`, `--type`, `--scope`, `--body`, `-a`.Faz commit do que está staged, depois das verificações. Flags: `-m`, `--type`, `--scope`, `--body`, `-a`.	nonão
`gtide save`	Stage and commit in one step. Flags: `-m`, `--type`, `--scope`, `--body`, `-f`.Faz stage e commit num passo só. Flags: `-m`, `--type`, `--scope`, `--body`, `-f`.	nonão
`gtide continue`	Finish an interrupted merge, rebase, cherry-pick or revert.Conclui um merge, rebase, cherry-pick ou revert interrompido.	nonão
`gtide abort`	Give up an interrupted operation. Asks first; `--yes` skips.Desiste de uma operação interrompida. Pergunta antes; `--yes` pula.	nonão
`gtide review <PR>`	Check out a Pull Request on a review branch. Flag: `--reset`.Baixa uma Pull Request numa branch de revisão. Flag: `--reset`.	API, fetchAPI, fetch
`gtide push`	Push the current branch and set its upstream. Flags: `--force`, `--yes`.Envia a branch atual e configura o upstream. Flags: `--force`, `--yes`.	pushpush
`gtide pr`	Push and open a Pull Request. Flags: `--base`, `--title`, `--body`, `--draft`, `--yes`.Envia e abre uma Pull Request. Flags: `--base`, `--title`, `--body`, `--draft`, `--yes`.	fetch, push, APIfetch, push, API
`gtide doctor`	Diagnose Git, repository, configuration, remote, base branch, hooks and PATH, changing nothing.Diagnostica Git, repositório, configuração, remote, branch base, hooks e PATH, sem alterar nada.	nonão
`gtide config [show\|validate]`	Print the effective configuration, or validate `.tide.yml`.Mostra a configuração efetiva, ou valida o `.tide.yml`.	nonão

Exit codesCódigos de saída

CodeCódigo	MeaningSignificado
`0`	Success.Sucesso.
`1`	General failure, including conflicts in `gtide update` and problems found by `gtide doctor`.Falha geral, incluindo conflitos no `gtide update` e problemas encontrados pelo `gtide doctor`.
`2`	Invalid command usage or arguments.Uso ou argumentos inválidos do comando.
`3`	Configuration invalid, or missing where required (including a missing `GITHUB_TOKEN` for `gtide pr`).Configuração inválida, ou ausente onde é obrigatória (incluindo a falta do `GITHUB_TOKEN` no `gtide pr`).
`4`	A policy rejected the operation (protected branch, commit message, secret).Uma política rejeitou a operação (branch protegida, mensagem de commit, secret).
`5`	External failure: Git, the network, or the GitHub API.Falha externa: Git, rede ou API do GitHub.
`6`	Unsafe repository state; nothing was changed.Estado inseguro do repositório; nada foi alterado.

When a hook rejects a command, Git itself reports a failure; the GiTide exit code applies when you run gtide directly.

Quando um hook rejeita um comando, é o próprio Git que reporta a falha; o código de saída do GiTide vale quando você executa o gtide diretamente.

Configuration keysChaves de configuração

KeyChave	DefaultPadrão	MeaningSignificado
`version`	`1`	Schema version. Only 1 is supported.Versão do schema. Só a 1 é suportada.
`remote`	`origin`	Remote used by update, review and pr.Remote usado por update, review e pr.
`branches.default_base`	`main`	Base for branches that match no pattern in `branches.base`.Base das branches que não casam com nenhum padrão de `branches.base`.
`branches.protected`	`[main]`	Branches where local hooks reject direct commits and pushes.Branches onde os hooks locais rejeitam commits e pushes diretos.
`branches.base`	nonenenhum	Map of branch pattern to base branch.Mapa de padrão de branch para branch base.
`update.strategy`	`merge`	`merge` or `rebase`.`merge` ou `rebase`.
`commits.convention`	`conventional`	The only supported convention.A única convenção suportada.
`commits.require_scope`	`false`	Require `type(scope):` instead of `type:`.Exige `type(scope):` em vez de `type:`.
`secrets.enabled`	`true`	Scan staged changes for likely secrets.Analisa as alterações staged em busca de prováveis secrets.
`secrets.custom_patterns`	nonenenhum	Extra detectors with `name` and `pattern`, at most 100.Detectores extras com `name` e `pattern`, no máximo 100.
`hooks.manage`	`true`	Whether `gtide init` installs hooks.Se o `gtide init` instala os hooks.