Todas as coleções

Espaços de trabalho

Um workspace do Buildprint é a forma como o CLI organiza um app do Bubble no disco. Ele materializa uma branch do Bubble como uma pasta comum de arquivos que você pode editar como código, e usa git nos bastidores para rastrear o que veio do Bubble, o que você alterou localmente e o que já foi aplicado de volta. Entender esse modelo explica como o Buildprint funciona por trás dos panos.

A raiz do app

Quando você clona um app, o CLI cria um diretório raiz do app. Por padrão, ele recebe o nome do ID do app, ou você pode substituir o local com --dir:

buildprint project clone <appId>
buildprint project clone <appId> --dir ./my-app

A raiz do app contém um único diretório oculto .buildprint/, que é o plano de controle para cada branch desse app:

  • .buildprint/app.json - configuração no nível do app: a versão do esquema, o appId do Bubble e a referência do token usada para autenticação.

  • .buildprint/remote.git - um repositório git bare compartilhado. Este é o repositório oficial para todos os snapshots, o estado publicado e o histórico local. Nenhum arquivo é jamais feito checkout aqui; o CLI transmite os commits diretamente para ele, e é isso que torna rápido clonar um app grande.

  • .buildprint/cache/ - caches locais do CLI (estado de verificação, índices de snapshot). Seguro para excluir; é regenerado sob demanda.

O CLI encontra a raiz do app subindo a partir de onde quer que você execute um comando até encontrar um .buildprint/ com um repositório bare e um app.json legível, então você pode executar comandos de qualquer lugar dentro do workspace.

Cada branch é um worktree do git

Cada branch do Bubble que você clona se torna um worktree do git que é um filho direto da raiz do app:

my-app/
  .buildprint/
    app.json
    remote.git/
  test/          <- worktree for the Bubble "test" branch
  live/          <- worktree for the Bubble "live" branch
  feature-x/     <- worktree for a feature branch

buildprint project clone usa como padrão a branch test. A branch editável do Bubble geralmente é Test, não main, então --branch main normalmente falhará - execute buildprint branch list <appId> para ver os nomes reais:

buildprint project clone <appId> --branch feature-x
buildprint project clone <appId> --branch live

Clonar uma segunda branch de um app que você já possui reutiliza a mesma raiz do app e o repositório bare compartilhado, adicionando um novo worktree irmão:

buildprint project clone <appId> --branch live && buildprint project clone <appId> --branch test

O nome da pasta e a branch do git feita checkout dentro dela estão vinculados: a pasta test/ precisa ter a branch test feita checkout. O CLI impõe isso e se recusa a operar em um worktree cujo HEAD não corresponda ao nome do diretório, ou em um que tenha sido movido para longe da raiz do app. Se você precisar de uma pasta de branch em outro lugar, recrie-a com project clone em vez de movê-la.

Os refs que rastreiam o estado

Como tudo é git, “o que o Bubble tem” e “o que eu apliquei” são apenas refs no repositório bare compartilhado. Existem três por branch:

  • refs/heads/<branch> - sua branch de trabalho. Este é o HEAD feito checkout no worktree, e os commits que você vai acumulando à medida que edita e aplica.

  • refs/bubble/<branch> - o último snapshot sincronizado a partir do Bubble. Ele fica fora de refs/heads/ para que git branch liste apenas suas branches de trabalho, e não snapshots brutos.

  • refs/published/<branch> - o último commit local que foi aplicado com sucesso ao Bubble.

Esses elementos se movem em momentos bem definidos:

  • Clone / seed. O CLI desmembra o app do Bubble obtido em arquivos, faz commit deles em refs/heads/<branch>, e aponta tanto refs/bubble/<branch> quanto refs/published/<branch> para esse mesmo commit. Neste instante, seu workspace, o snapshot do Bubble e o estado publicado do Bubble estão todos em acordo.

  • Sync. buildprint sync obtém o snapshot mais recente do Bubble, faz commit dele em refs/bubble/<branch>, e (a menos que você passe --no-merge) mescla esse ref de snapshot ao seu HEAD de trabalho. Se sua branch local não tinha alterações, isso é um fast-forward limpo; se você tinha edições, o git as mescla, e conflitos reais aparecem como conflitos comuns do git a serem resolvidos. --reset descarta as alterações locais e faz hard reset do worktree para o snapshot do Bubble.

  • Apply. buildprint apply compila o diff entre sua árvore de trabalho e o último snapshot em chamadas /write do Bubble e as envia. Quando o Bubble aceita a escrita, o CLI avança refs/published/<branch> para o commit atual do seu HEAD. Portanto, refs/published só avança após uma aplicação bem-sucedida e sempre marca exatamente o que o Bubble contém agora.

A branch git do worktree também acompanha um remote buildprint/<branch> que espelha refs/published/*, e é isso que permite ao git dizer o quão à frente do Bubble publicado está o seu trabalho local.

Por que isso torna a edição local segura

Como suas edições são commits em refs/heads/<branch> e o estado do Bubble fica fixado em refs/bubble e refs/published, o CLI sempre consegue responder com precisão a três perguntas:

  • Diffs. O que você mudou desde o último snapshot do Bubble? Isso é a comparação da sua árvore de trabalho com refs/bubble/<branch>. buildprint apply usa exatamente esse delta para decidir o que escrever.

  • Savepoints. Savepoints capturam pontos de restauração do editor do Bubble para a branch, e, como o histórico local é git de verdade, você também pode reverter seus arquivos para qualquer snapshot sem tocar no Bubble.

  • Detecção de drift. Comparar refs/published com refs/bubble diz ao CLI se o Bubble mudou enquanto você estava trabalhando desde a última aplicação, então uma aplicação desatualizada falha rapidamente localmente com orientação para sincronizar em vez de ser rejeitada pelo servidor.

Valide uma alteração com buildprint check antes de aplicar e, depois, aplique-a:

buildprint check
buildprint apply

Vários apps e branches lado a lado

Cada app vive na sua própria raiz de app com seu próprio .buildprint/remote.git; não há estado global compartilhado entre apps. Dentro de uma raiz de app, cada branch que você clona é outro worktree irmão, todos respaldados pelo mesmo repositório bare, então branches do mesmo app compartilham histórico de forma barata enquanto permanecem totalmente independentes no disco. Liste e inspecione o que você tem com:

buildprint project list
buildprint project info <appId>
buildprint branch list <appId>

Isso foi útil?