> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Branches

> Trabalhe em uma branch sem tocar no rascunho do projeto: publique commits imutáveis, escolha qual branch cada canal executa e promova seu trabalho para produção quando estiver pronto.

Por padrão, seu diretório local lê o **rascunho** do projeto: as mesmas linhas
que o Studio edita, vivas e mutáveis. Com branches você pode trabalhar contra
uma versão publicada, testá-la em um canal separado e levar o resultado para
produção quando estiver pronto — sem que ninguém veja o trabalho pela metade.

Uma **branch** guarda commits. Um **commit** é uma foto imutável de todos os
workflows do projeto, e é o que um canal serve aos seus usuários.

<Note>
  Esta página assume que você já vinculou o diretório com `jelou link` e baixou os
  workflows com `jelou pull`. Se ainda não fez isso, comece por
  [Projetos e canais](/pt/guias/cli/project).
</Note>

## As duas origens

Seu diretório lê de um único lugar por vez, e `jelou status` diz qual na
primeira linha.

| Origem       | O que é                            | Quem vê                                    |
| ------------ | ---------------------------------- | ------------------------------------------ |
| **Rascunho** | As linhas vivas que o Studio edita | Só é publicado com `jelou project publish` |
| **Branch**   | O commit de topo dessa branch      | Os canais apontados para essa branch       |

O rascunho é a origem padrão e é o que o resto da documentação do CLI descreve.
Tudo abaixo é o que muda quando você trabalha em uma branch.

## Mudar de origem

```bash theme={null}
jelou checkout dev            # lê a branch dev
jelou checkout draft          # volta para o rascunho
jelou checkout -b nova-branch # cria uma branch a partir de onde você está
jelou branch list             # quais branches existem e qual você lê
```

`jelou checkout <branch>` reescreve seus arquivos com o que essa branch serve.
Por isso ele recusa quando você tem edições não publicadas: publique-as antes ou
descarte-as com `jelou pull --accept-server`.

`jelou checkout -b <nome>` é a exceção e não toca em nenhum arquivo. Cria a
branch a partir do commit que você está lendo e leva junto seu trabalho em
andamento, então é a forma de dizer "isto que tenho pela metade vai virar uma
branch".

<Note>
  `draft` é um nome reservado, para que `jelou checkout draft` não seja ambíguo.
  Você não pode criar uma branch com esse nome.
</Note>

## Publicar em uma branch

Estando em uma branch, `jelou push` muda de significado: em vez de escrever o
rascunho, ele **publica um commit** e move a branch para ele.

```bash theme={null}
jelou push -m "menu de pedidos"    # publica os arquivos modificados
jelou push --dry-run               # mostra o que publicaria
```

Três coisas que vale saber:

* **O rascunho não é tocado.** Nada do que você publica em uma branch aparece no
  Studio até promover para a branch que o Studio lê.
* **Só o que mudou é enviado.** Os workflows e canais que você não tocou mantêm
  a versão que a branch já servia, então publicar um arquivo produz um commit
  completo do mesmo jeito.
* **O nome do commit é obrigatório.** Use-o para saber o que ele contém quando
  aparecer no histórico.

<Warning>
  `jelou push` recusa se a branch avançou desde o seu último pull. Outra pessoa
  publicou nesse meio-tempo e seu commit seria construído sobre um trabalho que
  você não viu. Rode `jelou pull`, revise e tente de novo.
</Warning>

### Conversas em andamento

Publicar move as conversas que estão pela metade para a versão nova no turno
seguinte. Se preferir que terminem na versão com que começaram, publique com
`--keep-pinned`.

```bash theme={null}
jelou push -m "hotfix" --keep-pinned
```

Vale apenas ao publicar em `master`, porque o ajuste é do projeto inteiro e não
de uma branch específica.

## Levar o trabalho para outra branch

```bash theme={null}
jelou promote master           # master serve o commit que você está lendo
jelou promote master -m "Release 12"
```

`jelou promote` faz outra branch servir o commit em que você está. A promoção
aparece no histórico da branch de destino com seu próprio identificador, e seu
diretório não muda: você continua na sua branch, no seu commit.

<Note>
  O commit do destino recebe um identificador diferente do de origem. É uma cópia,
  não o mesmo commit apontado de dois lados, e é por isso que fica registrado no
  histórico das duas branches.
</Note>

Ele recusa quando você tem trabalho local que o commit não contém — você estaria
promovendo algo diferente do que vê na tela. Publique antes, ou use
`--allow-dirty` se realmente quiser promover o que foi publicado e deixar suas
edições onde estão.

## Qual branch cada canal executa

Isso é independente do que seu diretório lê. Um canal pode estar servindo
`master` enquanto você trabalha em `dev`.

```bash theme={null}
jelou channels list --project 01H2XCEJQTG2H5V5NKCYW3J7Z2
jelou channels set-branch 01H2XCEJQTG2H5V5NKCYW3J7Z2 dev
```

A coluna **Branch** da listagem mostra o que cada canal executa. Em cinza
significa que nunca foi definido, então segue `master`.

`set-branch` vale imediatamente para conversas novas. Recusa se a branch ainda
não tem nada publicado.

<Tip>
  Aponte um canal de testes para a sua branch e deixe os de produção em `master`.
  Assim você testa com mensagens reais sem que nenhum usuário veja a mudança.
</Tip>

## Um ciclo completo

<Steps>
  <Step title="Crie a branch e edite">
    A branch sai do commit que você está lendo e leva junto seu trabalho em
    andamento.

    ```bash theme={null}
    jelou checkout -b promo-natal
    # edite workflows/*.json
    jelou workflow validate
    ```
  </Step>

  <Step title="Publique o primeiro commit">
    ```bash theme={null}
    jelou push -m "promoção de natal"
    ```

    O rascunho não é tocado: nada disso aparece no Studio ainda.
  </Step>

  <Step title="Teste em um canal">
    ```bash theme={null}
    jelou channels set-branch 01H2XCEJQTG2H5V5NKCYW3J7Z2 promo-natal
    ```

    Mande uma mensagem para o canal e verifique o comportamento com mensagens
    reais. Repita os passos anteriores até ficar como você quer.
  </Step>

  <Step title="Promova para produção">
    ```bash theme={null}
    jelou promote master -m "Promo natal"
    ```

    Agora `master` serve o mesmo commit que você testou.
  </Step>

  <Step title="Devolva o canal de testes">
    ```bash theme={null}
    jelou channels set-branch 01H2XCEJQTG2H5V5NKCYW3J7Z2 master
    ```

    Assim ele volta a seguir produção e fica livre para a próxima branch.
  </Step>
</Steps>

## Uma branch sem nada publicado

Um projeto novo nasce com `master` vazia, e criar uma branch a partir dali é
perfeitamente válido. Seu diretório fica em uma branch sem commits — `jelou
status` chama isso de *nothing published yet* — e o primeiro `jelou push`
escreve o commit inicial dela.

Ler uma branch vazia não é um erro. Pedir uma branch que não existe é outra
coisa, e essa sim falha.

## O que precisa do rascunho

Estes comandos escrevem o rascunho, então recusam enquanto você lê uma branch.
Volte com `jelou checkout draft` para usá-los.

| Comando                        | Por quê                                                                                         |
| ------------------------------ | ----------------------------------------------------------------------------------------------- |
| `jelou project publish`        | Publica o **rascunho**, não seus arquivos: substituiria o que você acabou de publicar na branch |
| `jelou incoming accept-local`  | Despacha seu arquivo contra o rascunho                                                          |
| `jelou incoming accept-server` | Resolve um conflito capturado contra o rascunho                                                 |
| `jelou status --check-remote`  | Apenas esta flag; `jelou status` sozinho funciona nas duas origens                              |

Depois de um `jelou push` em uma branch não há mais nada a executar: o commit
existe e a branch já aponta para ele.

O contrário também vale: `jelou promote` precisa estar em uma branch, porque o
rascunho não tem nenhum commit para promover.

## Workflows em TypeScript

Se você adotou um workflow para TypeScript com `jelou workflow adopt`, esse
arquivo é a fonte e o CLI nunca escreve JSON por cima, nem ao trocar de branch.

Quando o `.ts` difere do que a branch serve, `jelou pull` avisa e `jelou status`
o marca como modificado. A partir daí você decide:

* **Publicar o seu** — `jelou push`, que o envia como um commit novo.
* **Ficar com o da branch** — apague o `.ts` e rode `jelou pull` de novo.