Tutorials

Step-by-step guides for the tide CLI, written from its source and README. Output blocks mirror the CLI’s real format; names and values are examples.

Guides for Git Tide 1.0. They assume you installed a release or built it from source.

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

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

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

  1. 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
  2. Download it and put it on your PATHBaixe e coloque no seu PATH

    Pick the file for your system on the download section or the Releases page. On macOS and Linux you can do it all from the terminal; the script checks the download against checksums.txt before installing:

    Escolha o arquivo do seu sistema na seção de download ou na página de Releases. No macOS e no Linux dá para fazer tudo pelo terminal; o script confere o download com o checksums.txt antes de instalar:

    $ repo=https://github.com/Cellestias/git-tide
    $ version=$(curl -fsSLI -o /dev/null -w '%{url_effective}' "$repo/releases/latest" | sed 's#.*/##')
    $ os=$(uname -s | tr '[:upper:]' '[:lower:]')
    $ case $(uname -m) in x86_64 | amd64) arch=amd64 ;; arm64 | aarch64) arch=arm64 ;; esac
    $ name=tide_${version}_${os}_${arch}
    $ curl -fsSLO "$repo/releases/download/$version/$name.tar.gz"
    $ curl -fsSLO "$repo/releases/download/$version/checksums.txt"
    $ grep " $name.tar.gz\$" checksums.txt | { sha256sum -c - 2>/dev/null || shasum -a 256 -c -; }
    tide_v1.0.0_linux_amd64.tar.gz: OK
    $ tar -xzf "$name.tar.gz"
    $ sudo install -m 755 "$name/tide" /usr/local/bin/tide
    $ tide --version

    On Windows, download the .zip, extract tide.exe, and add its folder to your PATH; the repository README has the PowerShell commands. To build from source instead, clone the repository and run make install (needs Go 1.26.10 or newer).

    No Windows, baixe o .zip, extraia o tide.exe e adicione a pasta dele ao seu PATH; o README do repositório tem os comandos de PowerShell. Para compilar do código-fonte, clone o repositório e execute make install (precisa do Go 1.26.10 ou mais novo).

  3. Set up your repositoryConfigure o seu repositório

    Inside the repository, run tide init. It creates .tide.yml and installs three Git hooks. Then run tide doctor to check everything.

    Dentro do repositório, execute tide init. Ele cria o .tide.yml e instala três hooks do Git. Depois execute tide doctor para conferir tudo.

    $ cd your-repo
    $ tide init
    ✓ hook pre-commit: installed
    ✓ hook commit-msg: installed
    ✓ hook pre-push: installed
    ✓ created /home/dev/tool/.tide.yml (base branch: main)
    $ tide 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
    ✓ tide on PATH: found

    The base branch is detected from origin/HEAD, then main, then master. Override it with tide init --base stage.

    A branch base é detectada a partir de origin/HEAD, depois main, depois master. Troque-a com tide init --base stage.

  4. 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 tide configuration"

A day with Tide: from branch to Pull RequestUm dia com o Tide: 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.

  1. Start from a fresh baseComece de uma base atualizada

    tide 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 tide 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.

    $ tide create feature/login
      base: stage (from .tide.yml)
    → Fetching origin/stage
    ✓ Created and switched to feature/login from origin/stage
  2. 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 Tide stage and commit in one step. It runs the same checks first (see the next tutorial).

    Ou deixe o Tide fazer stage e commit num passo só. Ele roda as mesmas verificações antes (veja o próximo tutorial).

    $ tide save -m "feat: add login form" -f src/login.go
    → Committed a1b2c3d on feature/login: feat: add login form (1 file)
  3. Publish the branchPublique a branch

    $ tide push
    → Pushing feature/login to origin
    ✓ Pushed feature/login to origin and set it as upstream
  4. 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:

    $ tide update
    → Fetching origin/stage
    → Updating local stage
    → Integrating stage into feature/login (merge)
    ✓ Updated to include stage
  5. Open the Pull RequestAbra a Pull Request

    tide 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 tide 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=...
    $ tide 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

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

O tide commit faz commit do que já está staged. O tide 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.

$ tide commit -m "feat(auth): add login form"
$ tide commit --type feat --scope auth -m "add login form"   # builds "feat(auth): add login form"
$ tide commit -a -m "fix: handle empty token"                # also stages tracked changes
$ tide save -m "feat: add login form"                       # every change, new files included
$ tide save -m "feat(auth): add login form" -f src/auth/login_form.tsx
$ tide save --type fix -m "handle empty token" -f api/token.go -f api/token_test.go
$ tide save -m "docs: update readme" -f docs/                # a directory stages everything under it
$ tide 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)
FlagFlagEffectEfeito
-m, --messageThe commit message (required).A mensagem do commit (obrigatória).
--type, --scopeBuild type(scope): message from -m. --scope needs --type.Monta type(scope): message a partir do -m. O --scope exige o --type.
--bodyCommit body, after a blank line.Corpo do commit, depois de uma linha em branco.
-a, --alltide commit only: stage modifications and deletions of tracked files first. Untracked files are never added.Só no tide commit: faz stage das modificações e remoções de arquivos rastreados antes. Arquivos não rastreados nunca são adicionados.
-f, --filetide 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 tide 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, Tide 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 Tide never uses --no-verify.

Antes de commitar qualquer coisa, o Tide 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 Tide nunca usa --no-verify.

Keep a branch up to dateMantenha uma branch atualizada

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

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

  1. checks that the repository is in a safe state;
  2. fetches the base branch from the configured remote;
  3. fast-forwards the local base branch to match (it never creates merge commits or discards commits on the base);
  4. integrates the base into your branch with merge (default) or rebase;
  5. leaves you on your original branch and reports whether anything changed.
  1. confere se o repositório está num estado seguro;
  2. busca a branch base do remote configurado;
  3. avança a branch base local para igualar (nunca cria commits de merge nem descarta commits da base);
  4. integra a base na sua branch com merge (padrão) ou rebase;
  5. deixa você na sua branch original e informa se algo mudou.
$ tide update            # base resolved from .tide.yml
$ tide 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ê.

$ tide update
✗ uncommitted changes would be at risk: src/login.go, README.md
  hint: commit or stash them, then re-run `tide 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.

$ tide 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 tide 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 tide abort.

Edite os arquivos em conflito, faça git add neles e execute tide 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 tide abort.

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

tide 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 tide continue again.

O tide 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 tide continue outra vez.

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

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

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

$ tide 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
ColumnColunaMeaningSignificado
UPSTREAMAhead (↑) 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.
BASEThe base branch from .tide.yml with ahead/behind against it.A branch base do .tide.yml, com quantos commits à frente/atrás dela.
STATUSprotected (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 AUTHORAuthor 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.

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

Switching safelyTrocando com segurança

tide change (alias tide 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, Tide lists them and refuses.

O tide change (alias tide 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 Tide as lista e recusa.

$ tide change two-fa
✓ Switched to feature/two-fa
  ↓2 behind stage: run `tide update`
$ tide change -             # previous branch
$ tide 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. Tide 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 Tide nunca faz stash por você.

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

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

Creating branchesCriando branches

FlagFlagEffectEfeito
--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.
--localStart from the local branch and make no network call.Começa da branch local e não faz chamada de rede.
--trackThe 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.
--pushAlso 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-switchCreate 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

tide 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 tide 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.

$ tide 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: tide review 123, tide 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: tide review 123, tide 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, Tide 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 Tide 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

tide 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. tide review and tide branch --github only need a token for private repositories. Pushing uses Git’s own authentication, not this token.

O tide 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 tide review e o tide 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 Tide looks for itOnde o Tide procura o token

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

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

  1. the GITHUB_TOKEN environment variable;
  2. the GH_TOKEN environment variable;
  3. a GITHUB_TOKEN= or GH_TOKEN= line in the .env file at the repository root.
  1. a variável de ambiente GITHUB_TOKEN;
  2. a variável de ambiente GH_TOKEN;
  3. 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

Tide 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 Tide 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
$ tide config validate
✓ /home/dev/tool/.tide.yml is valid
$ tide 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: tide update main or tide pr --base main.

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

Understand the hooksEntenda os hooks

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

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

HookHookRejectsRejeita
pre-commitA 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-msgA message that is not a Conventional Commit.Uma mensagem que não é um Conventional Commit.
pre-pushA 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 `tide:allow-secret` to that line

For a false positive, put tide: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 tide: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 tide:allow-conflict-marker on that line. tide commit and tide 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 tide:allow-conflict-marker naquela linha. O tide commit e o tide 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 Tide’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 Tide, 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 “tide: not found on PATH; skipping … checks”Os hooks imprimem “tide: not found on PATH; skipping … checks”

Git cannot find the binary. Put tide 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 tide 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 tide doctor. Check that core.hooksPath is not pointing elsewhere (git config core.hooksPath) and that the hook files are executable. Re-run tide init after changing the hooks directory.

Execute o tide 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 tide init de novo depois de mudar o diretório de hooks.

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

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

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

tide update: “cannot fast-forward local <base>”tide 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 tide:allow-secret to that line, or narrow your custom pattern.

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

tide pr: “GITHUB_TOKEN is not set”tide 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). tide 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 tide 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

Tide 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 Tide 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.

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

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

Edite os arquivos listados para remover os marcadores de conflito, faça git add neles e execute tide 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 tide: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 tide:allow-conflict-marker numa linha que realmente contenha um.

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

The configured remote must be a github.com URL (HTTPS, ssh://, or git@github.com: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 git@github.com:owner/repo.git). Mude o remote no .tide.yml se o seu remote do GitHub não for o origin.

ReferenceReferência

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

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

CommandsComandos

CommandComandoWhat it doesO que fazNetworkRede
tide initCreate .tide.yml and install the hooks. Flags: --base, --no-hooks.Cria o .tide.yml e instala os hooks. Flags: --base, --no-hooks.nonão
tide 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 --pushfetch, push com --push
tide change <branch>Switch branches safely. Alias switch. Flag: --carry.Troca de branch com segurança. Alias switch. Flag: --carry.nonão
tide branchList 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
tide update [branch]Bring the base branch into the current branch.Traz a branch base para a branch atual.fetchfetch
tide commitCommit 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
tide saveStage 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
tide continueFinish an interrupted merge, rebase, cherry-pick or revert.Conclui um merge, rebase, cherry-pick ou revert interrompido.nonão
tide abortGive up an interrupted operation. Asks first; --yes skips.Desiste de uma operação interrompida. Pergunta antes; --yes pula.nonão
tide 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
tide pushPush the current branch and set its upstream. Flags: --force, --yes.Envia a branch atual e configura o upstream. Flags: --force, --yes.pushpush
tide prPush 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
tide doctorDiagnose 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
tide 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ódigoMeaningSignificado
0Success.Sucesso.
1General failure, including conflicts in tide update and problems found by tide doctor.Falha geral, incluindo conflitos no tide update e problemas encontrados pelo tide doctor.
2Invalid command usage or arguments.Uso ou argumentos inválidos do comando.
3Configuration invalid, or missing where required (including a missing GITHUB_TOKEN for tide pr).Configuração inválida, ou ausente onde é obrigatória (incluindo a falta do GITHUB_TOKEN no tide pr).
4A policy rejected the operation (protected branch, commit message, secret).Uma política rejeitou a operação (branch protegida, mensagem de commit, secret).
5External failure: Git, the network, or the GitHub API.Falha externa: Git, rede ou API do GitHub.
6Unsafe 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 Tide exit code applies when you run tide directly.

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

Configuration keysChaves de configuração

KeyChaveDefaultPadrãoMeaningSignificado
version1Schema version. Only 1 is supported.Versão do schema. Só a 1 é suportada.
remoteoriginRemote used by update, review and pr.Remote usado por update, review e pr.
branches.default_basemainBase 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.basenonenenhumMap of branch pattern to base branch.Mapa de padrão de branch para branch base.
update.strategymergemerge or rebase.merge ou rebase.
commits.conventionconventionalThe only supported convention.A única convenção suportada.
commits.require_scopefalseRequire type(scope): instead of type:.Exige type(scope): em vez de type:.
secrets.enabledtrueScan staged changes for likely secrets.Analisa as alterações staged em busca de prováveis secrets.
secrets.custom_patternsnonenenhumExtra detectors with name and pattern, at most 100.Detectores extras com name e pattern, no máximo 100.
hooks.managetrueWhether tide init installs hooks.Se o tide init instala os hooks.