# Andares

Andares permitem trabalhar em branches isolados sem sair do seu workspace. Cada andar é uma cópia completa do seu repositório que compartilha armazenamento com o original — graças ao copy-on-write do APFS (Apple Filesystem), criar um andar é muito rápido e usa quase nenhum espaço extra em disco.

## Por que Andares?

Quando você está imerso em uma tarefa e precisa mudar de contexto — talvez para corrigir um bug em outra branch, revisar um PR ou experimentar uma abordagem diferente — normalmente teria que fazer stash do seu trabalho, trocar de branch e lembrar onde parou depois.

Andares eliminam esse atrito. Crie um novo andar e você terá um ambiente completamente isolado com seu próprio terminal, branch e working tree. Seu workspace original permanece exatamente como você deixou.

## Criando um andar

1. Clique no botão de andar no canto inferior direito do app, ao lado do minimapa.
2. O canvas se reposiciona em um espaço 3D — clique no botão de novo andar.
3. Dê um nome (ex: "Corrigir bug de login").
4. Se você tiver um repositório git inicializado, escolha criar uma nova branch ou usar uma existente.
5. Opcionalmente ative **Clonar layout do Térreo** para duplicar todos os elementos (notas, terminais, blocos de texto) do Térreo para o novo andar.
6. Clique em **Criar**.

O Maestri clona seu repositório instantaneamente e faz checkout da branch do andar. Qualquer terminal que você adicionar no novo andar funciona neste ambiente isolado — você pode até rodar servidores de desenvolvimento, IDEs e comandos de build simultaneamente sem conflitos.

## Trabalhando em um andar

Cada andar é um repositório git real. Você pode:

- Fazer commits, criar branches, rodar testes
- Abrir múltiplos terminais no mesmo andar
- Ver alterações de arquivos e estatísticas de diff no painel do andar
- Verificar conflitos de merge antes de aterrissar

A branch do andar é espelhada no seu repositório original, então outras ferramentas (GitHub, seu IDE) podem vê-la também.

## Aterrissando um andar

Quando seu trabalho estiver pronto, é hora de aterrissar. Certifique-se de que todas as alterações estão commitadas (sem working tree sujo), então clique em **Aterrissar** no painel do andar.

A interface de aterrissagem mostra a branch do seu andar à esquerda e a branch de destino (térreo) à direita, com um ícone de avião representando a transferência de commits.

Selecione em qual branch aterrissar:

- **Mesma branch do andar** — O Maestri transfere os commits diretamente para o repositório original.
- **Branch diferente** — O Maestri também realiza um merge (se não houver conflitos).

Após selecionar, você verá uma prévia do merge com estatísticas de diff e quaisquer conflitos potenciais.

Clique em **Merge** para completar a aterrissagem. O Maestri busca os commits do seu andar para o repositório original e os mescla na branch de destino.

Nota

Resolver conflitos de merge não é suportado atualmente na interface de andares. Resolva os conflitos no seu IDE ou terminal antes de mesclar.

## Hooks

Hooks permitem automatizar comandos que rodam em momentos-chave do ciclo de vida de um andar — quando ele é criado, quando você quer executar tarefas, e quando ele é excluído.

Para configurar hooks, clique com o botão direito no botão de andar no canvas e selecione **Configure Hooks...**.

### Tipos de hooks

Existem três tipos de hooks:

- **Setup** — Roda quando um andar é criado. Use para instalar dependências, vincular serviços ou preparar o ambiente. Você pode ativar **Auto-run** para executar os comandos de setup automaticamente quando o andar é criado.
- **Run** — Roda quando você clica no botão play. Use para iniciar servidores de desenvolvimento, rodar testes ou qualquer tarefa sob demanda.
- **Teardown** — Roda quando um andar é excluído. Use para limpar recursos, desvincular serviços ou remover arquivos temporários.

Cada hook suporta múltiplos comandos — clique em **\+ Add command** para adicionar mais.

### Variáveis de ambiente

O Maestri fornece variáveis de ambiente que você pode usar nos seus comandos de hook:

- `$MAESTRI_FLOOR_NAME` — O nome do andar
- `$MAESTRI_BRANCH_NAME` — O nome da branch git
- `$MAESTRI_FLOOR_PATH` — O diretório de trabalho do andar
- `$MAESTRI_ROOT_PATH` — A raiz original do projeto
- `$MAESTRI_PROJECT_NAME` — O nome do workspace

### Acesso rápido

Uma vez configurados, seus hooks ficam sempre acessíveis pelo ícone de raio (⚡) ao lado do botão de andar no canvas. A partir dele você pode ver todos os seus hooks agrupados por tipo e executá-los individualmente ou todos de uma vez com **Run All**.

## Renomeando um andar

Clique com o botão direito no indicador de andar para renomeá-lo. Isso é útil quando o escopo do seu trabalho muda ou você quer um nome mais descritivo.

## Excluindo um andar

Clique no **x** em um andar para excluí-lo. Você pode escolher:

- **Manter a branch** — a branch permanece no seu repositório para uso posterior
- **Excluir a branch** — remove tanto o andar quanto sua branch

O diretório clonado é sempre removido, liberando qualquer espaço em disco usado por arquivos divergentes.

## Requisitos

Andares precisam de duas coisas para funcionar:

- **Volume APFS** — Andares usam clonagem copy-on-write, que só funciona em APFS (o padrão em Macs modernos).
- **Repositório Git** — Seu workspace deve ser um repo git.

## Como funciona

Por baixo dos panos, andares usam clonagem APFS instantânea. O clone compartilha todos os arquivos inalterados com o original — apenas arquivos modificados ocupam espaço adicional.

Quando você aterrissa um andar, o Maestri usa `git fetch` para puxar commits do clone de volta para seu repositório original, depois faz merge usando comandos git plumbing para evitar perturbar sua working tree.

Andares são armazenados em um diretório `.maestri/floors` ao lado do seu projeto. Este diretório é automaticamente limpo quando você exclui o último andar.