Executar operações Git nas pastas Git (Repos) do Databricks

O artigo descreve como executar operações comuns do Git em seu workspace do Databricks usando pastas Git, incluindo clonagem, ramificação, confirmação e envio por push.

Clonar um repositório conectado a um repositório Git remoto

  1. Na barra lateral, selecione workspace e, em seguida, navegador para a pasta em que você deseja criar o clone do repositório Git.

  2. Clique na seta para baixo à direita do Adicionar no canto superior direito do workspace e selecione pasta Git na lista suspensa.

    Adicionar a interface do usuário do repositório.

  3. Na caixa de diálogo Criar pasta Git, forneça as seguintes informações:

    • A URL do repositório Git que você deseja clonar, no formato https://example.com/organization/project.git
    • O provedor Git para o repositório que você deseja clonar. As opções incluem GitHub, GitHub Enterprise, GitLab e Azure DevOps (Azure Repos)
    • O nome da pasta em seu workspace que conterá o conteúdo do repositório clonado
    • Se você usará ou não o check-out esparso, no qual somente subdiretórios especificados usando um padrão de cone são clonados

    Clone da interface do usuário da pasta Git.

Nesta fase, você tem a opção de clonar apenas um subconjunto dos diretórios do seu repositório usando o sparse checkout. Isso será útil se o repositório for maior que os limites suportados pelo Databricks

  1. Clique em Criar pasta Git. O conteúdo do repositório remoto é clonado para o repositório do Databricks e você pode começar a trabalhar com eles usando operações Git com suporte por meio de seu workspace.

Prática recomendada: Colaborando em pastas Git

As pastas Git do Databricks se comportam efetivamente como clientes Git inseridos em seu workspace para que os usuários possam colaborar usando controle de origem baseado em Git e controle de versão. Para tornar a colaboração em equipe mais eficaz, use uma pasta Git do Databricks separada mapeada para um repositório Git remoto para cada usuário que trabalha em um branch de desenvolvimento próprio. Embora vários usuários possam contribuir com conteúdo para uma pasta Git, apenas um usuário designado deve executar operações do Git, como pull, push, commit e alternar branch. Se vários usuários executarem operações em uma pasta Git, o gerenciamento do branch poderá se tornar difícil e propenso a erros, especialmente em uma situação na qual um usuário alterna um branch e, de maneira não intencional, faz o mesmo para todos os outros usuários dessa pasta.

Para compartilhar uma pasta Git com um colaborador, clique em Copiar link para criar pasta Git no banner na parte superior do workspace do Databricks. Essa ação copia uma URL para a área de transferência local, que pode ser enviada a outro usuário. Quando o usuário destinatário carregar essa URL em um navegador, ele será levado ao espaço de trabalho, no qual poderá criar sua própria pasta Git clonada a partir do mesmo repositório Git remoto. Eles verão um diálogo modal Criar pasta Git na interface do usuário, preenchida previamente com os valores obtidos da sua própria pasta Git. Quando eles clicam no botão azul Criar pasta Git no modal, o repositório Git é clonado no espaço de trabalho sob a pasta de trabalho atual deles, onde podem agora trabalhar diretamente com ele.

Clique no botão Copiar link para a pasta Git no banner para compartilhar a configuração do repositório Git para a pasta com outro usuário na sua organização Databricks

Ao acessar a pasta Git de outra pessoa em um espaço de trabalho compartilhado, clique em Criar pasta Git no banner na parte superior. Essa ação abre o diálogo Criar pasta Git para você, preenchida previamente com a configuração do repositório Git que a suporta.

Ao exibir a pasta Git de outro usuário, clique no botão Criar pasta Git no banner para fazer uma cópia dessa pasta no seu próprio espaço de trabalho

Importante

Atualmente, você não pode usar a CLI do Git para executar operações do Git em uma pasta Git. Se você clonar um repositório Git usando a CLI por meio do terminal da Web de um cluster, os arquivos não serão exibidos na interface do usuário do Azure Databricks.

Acessar a caixa de diálogo do Git

Você pode acessar a caixa de diálogo do Git de um notebook ou do navegador de pastas Git do Databricks.

  • Em um notebook, clique no botão ao lado do nome do notebook que identifica o Git branch atual.

    Botão de diálogo do Git no notebook.

  • No navegador de pastas Git do Databricks, clique no botão à direita do nome do repositório. Você também pode clicar com o botão direito do mouse no nome do repositório e selecionar Git… no menu.

    Botão de diálogo Git e menu Git no navegador do repositório.

Você verá uma caixa de diálogo em tela inteira na qual poderá executar operações do Git.

A caixa de diálogo usada para executar operações Git em um workspace do Databricks.

  1. Seu branch de trabalho atual. Você pode selecionar outros brunchs aqui. Se outros usuários tiverem acesso a essa pasta Git, alterar o branch também alterará o branch para eles se eles compartilharem o mesmo workspace. Consulte uma melhor prática para evitar esse problema.
  2. O botão para criar um novo branch.
  3. A lista de ativos de arquivo e subpastas verificadas no branch atual.
  4. Um botão que leva você ao seu provedor Git e mostra o histórico atual do branch.
  5. O botão para extrair conteúdo do repositório Git remoto.
  6. Caixa de texto em que você adiciona uma mensagem de confirmação e uma descrição expandida opcional para suas alterações.
  7. O botão para confirmar seu trabalho no branch de trabalho e efetuar push do branch atualizado para o repositório Git remoto.

Clique no Menu kebab kebab no canto superior direito para escolher entre outras operações de branch do Git, como uma redefinição dura, uma mesclagem ou uma troca de base.

Menu suspenso no diálogo da pasta Git para operações de branch.

Esta é a sua casa para executar operações do Git na pasta Git do workspace. Você está limitado às operações do Git apresentadas na interface do usuário.

Criar uma nova ramificação

Você pode criar uma nova ramificação com base em uma ramificação existente na caixa de diálogo do Git:

Nova ramificação do diálogo do Git.

Alternar para um branch diferente

Você pode alternar (fazer checkout) para um branch diferente usando a lista suspensa do branch na caixa de diálogo do Git:

Alternar a caixa de diálogo Git para um branch diferente

Importante

Depois de fazer check-out de um branch em uma pasta Git, sempre há uma chance de o branch ser excluído no repositório Git remoto por outra pessoa. Se um branch for excluído no repositório remoto, a versão local poderá permanecer presente na pasta Git associada por até sete dias. As ramificações locais no Databricks não podem ser excluídas, portanto, se você precisar removê-las, deverá também excluir e clonar novamente o repositório.

Faça commit das alterações e efetue push delas para o repositório Git remoto

Quando você adicionou novos notebooks ou arquivos ou fez alterações em notebooks ou arquivos existentes, a interface de usuário da pasta do Git realça as alterações.

Diálogo do Git com as alterações destacadas.

Adicione uma mensagem de confirmação necessária para as alterações e clique em Fazer commit e Push para efetuar push dessas alterações para o repositório remoto do Git.

Se você não tiver permissão para confirmar a ramificação padrão, como main, crie uma nova ramificação e use a interface do provedor do Git para criar uma PR (pull request) para mesclá-la na ramificação padrão.

Observação

Alterações do pull do repositório do Git remoto

Para efetuar pull de alterações do repositório Git remoto, clique em Efetuar Pull na caixa de diálogo operações do Git. Os notebooks e outros arquivos são atualizados automaticamente para a versão mais recente em seu repositório Git. Se as alterações efetuadas no repositório remoto entrarem em conflito com as alterações locais no Databricks, será necessário resolver os conflitos mesclados.

Importante

As operações do Git que e pull em alterações upstream limpam o estado do notebook. Para obter mais informações, consulte Alterações de entrada limpam o estado do notebook.

Mesclar ramificações

Acesse a operação de Mesclagem do Git selecionando-a no kebab Menu kebab no canto superior direito da caixa de diálogo de operações Git.

A função mesclar nas pastas Git do Databricks mescla uma ramificação em outra usando git merge. Uma operação de mesclagem é uma forma de combinar o histórico de confirmações de uma ramificação em outra ramificação; a única diferença é a estratégia usada para alcançar esse objetivo. Para iniciantes no Git, recomendamos o uso de mesclagem (em vez de troca de base) porque não requer efetuar push forçado para uma ramificação e, portanto, não reescreve o histórico de confirmações.

  • Se existir um conflito de mesclagem, resolva-o na interface do usuário das pastas Git.
  • Se não houver conflito, a mesclagem será enviada para o repositório Git remoto usando git push.

Rebase um branch em outro branch

Acesse a operação de Troca de base do Git selecionando-a no menu do kebab Menu kebab no canto superior direito da caixa de diálogo de operações Git.

A troca de base altera o histórico de confirmações de uma ramificação. Como git merge, git rebase integra mudanças de uma ramificação para outra. A troca de base faz o seguinte:

  1. Salva as confirmações na sua ramificação atual em uma área temporária.
  2. Redefine a ramificação atual para a ramificação escolhida.
  3. Reaplica cada confirmação individual salva anteriormente na ramificação atual, resultando em um histórico linear que combina as alterações das duas ramificações.

Aviso

O uso de troca de base pode causar problemas de controle de versão para colaboradores trabalhando no mesmo repositório.

Um fluxo de trabalho comum é trocar a base de uma ramificação de recurso na ramificação principal.

Para trocar a base de uma ramificação em outra ramificação:

  1. No menu Ramificação na interface do usuário de pastas Git, selecione a ramificação que você deseja trocar a base.

  2. Selecione Trocar base no menu de kebab.

    Função de troca de base do Git no menu kebab.

  3. Selecione o branch cuja base você deseja trocar.

    A operação de troca de base integra as alterações da ramificação que você escolher aqui na ramificação atual.

As pastas Git do Databricks executam git commit e git push --force para atualizar o repositório Git remoto.

Resolver conflitos de mesclagem

Os conflitos de mesclagem acontecem quando dois ou mais usuários do Git tentam mesclar alterações nas mesmas linhas de um arquivo em uma ramificação comum e o Git não consegue escolher as alterações "certas" a serem aplicadas. Os conflitos de mesclagem também podem ocorrer quando um usuário tenta efetuar pull ou mesclar alterações de outra ramificação em uma ramificação com alterações não confirmadas.

GIF animado que mostra um conflito de mesclagem comum decorrente de alterações não confirmadas durante um pull do git

Se uma operação como pull, trocar base ou mesclar causar um conflito de mesclagem, a interface de usuário das pastas Git mostrará uma lista de arquivos com conflitos e opções para resolver os conflitos.

Você tem duas opções principais:

  • Use a interface de usuário das pastas Git para resolver o conflito.
  • Interrompa a operação do Git, descarte manualmente as alterações no arquivo conflitante e tente a operação do Git novamente.

GIF animado mostrando um conflito de mesclagem em uma interface do usuário da pasta Git do Databricks

Ao resolver conflitos de mesclagem com a interface do usuário das pastas Git, você deve escolher entre resolver manualmente os conflitos no editor ou manter todas as alterações de entrada ou atuais.

Manter Todas as Atuais ou Aceitar as Alterações de Entrada

Se souber que apenas deseja manter todas as alterações atuais ou de entrada, clique no botão à direita do nome do arquivo no painel do seu notebook e selecione Manter todas as alterações atuais ou Fazer todas as alterações de entrada. Clique no botão com o mesmo rótulo para confirmar as alterações e resolver o conflito.

O painel da interface do usuário do notebook do Databricks, mostrando as opções suspensas para resolução de conflitos de mesclagem

Dica

Está em dúvida sobre qual opção escolher? A cor de cada opção corresponde às respectivas alterações de código que ela manterá no arquivo.

Resolvendo manualmente os conflitos

A resolução manual de conflitos permite determinar quais das linhas conflitantes devem ser aceitas na mesclagem. Para conflitos de mesclagem, resolva o conflito editando diretamente o conteúdo do arquivo com os conflitos.

GIF animado mostrando uma resolução manual de um conflito de mesclagem

Para resolver o conflito, selecione as linhas de código que deseja preservar e exclua todo o resto, incluindo os marcadores de conflito de mesclagem do Git. Quando terminar, selecione Marcar como Resolvido.

Se você decidir que fez as escolhas erradas ao resolver os conflitos de mesclagem, clique no botão Anular para anular o processo e desfazer tudo. Uma vez resolvidos todos os conflitos, clique na opção Continuar Mesclagem ou Continuar Troca de Base para resolver o conflito e concluir a operação.

Git reset

Nas pastas Git do Databricks, você pode executar um Git reset na interface do usuário do Azure Databricks. A redefinição do Git nas pastas Git do Databricks é equivalente a git reset --hard combinado com git push --force.

A redefinição do Git substitui o conteúdo e o histórico da ramificação pelo estado mais recente de outra ramificação. Você pode usar isso quando as edições estão em conflito com a ramificação upstream, e você não se importa em perder essas edições ao redefinir para a ramificação upstream. Leia mais sobre git reset –hard.

Redefinir para uma ramificação upstream (remota)

Com git reset neste cenário:

  • Você redefiniu a ramificação selecionada (por exemplo, feature_a) para uma ramificação diferente (por exemplo, main).
  • Você também redefine a ramificação upstream (remota) feature_a para principal.

Importante

Ao redefinir, você perde todas as alterações não confirmadas e confirmadas na versão local e remota da ramificação.

Para redefinir uma ramificação para uma ramificação remota:

  1. Na interface do usuário das pastas Git, no menu Branch, escolha a ramificação que você deseja redefinir.

    Seletor de branch na interface do usuário das pastas Git.

  2. Selecione Redefinir no menu kebab.

    Operação de reinicialização do Git no menu kebab.

  3. Selecione o branch a ser redefinido.

    Diálogo reset --hard do Git.

Configurar o modo de check-out esparso

O check-out esparso é uma configuração do lado do cliente que permite clonar e trabalhar apenas com um subconjunto dos diretórios dos repositórios remotos no Databricks. Isso é especialmente útil se o tamanho do repositório está além dos limites com suporte do Databricks.

Você pode usar o modo de Check-out esparso ao adicionar (clonar) um novo repositório.

  1. Na caixa de diálogo Adicionar pasta Git, abra Avançado.

  2. Selecione Modo de check-out esparso.

    Opção de check-out esparso na caixa de diálogo Adicionar da pasta do Git.

  3. Na caixa Padrões de cone, especifique os padrões de check-out de cone desejados. Separe diferentes padrões com quebras de linha.

No momento, não é possível desabilitar o check-out esparso de um repositório no Azure Databricks.

Como funcionam os padrões de cone

Para entender como o padrão de cone funciona no modo de check-out esparso, consulte o diagrama a seguir que representa a estrutura do repositório remoto.

Estrutura do repositório remoto sem check-out esparso.

Se você selecionar o Modo de check-out esparso, mas não especificar um padrão de cone, o padrão de cone será aplicado. Isso inclui apenas os arquivos na raiz e nenhum subdiretório, resultando em uma estrutura de repositório como a seguinte:

Check-out esparso: padrão de cone padrão.

Definir o padrão de cone do check-out esparso como parent/child/grandchild faz com que todo o conteúdo do diretório grandchild seja incluído recursivamente. Os arquivos imediatamente em /parent, /parent/child e no diretório raiz também são incluídos. Consulte a estrutura do diretório no seguinte diagrama:

Check-out esparso: especifique o padrão de cone da pasta pai-neto-filho.

Você pode adicionar vários padrões separados por quebras de linha.

Observação

Não há suporte para comportamentos de exclusão (!) na sintaxe de padrão de cone do Git.

Modificar as configurações do check-out esparso

Após um repositório ser criado, o padrão de cone do check-out esparso pode ser editado em Configurações > Avançado > Padrões de cone.

Observe o seguinte comportamento:

  • A remoção de uma pasta do padrão de cone a remove do Databricks se não houver alterações não confirmadas.

  • Adicionar uma pasta por meio da edição do padrão de cone de check-out esparso a adiciona ao Databricks sem exigir um pull adicional.

  • Os padrões de check-out esparso não podem ser alterados para remover uma pasta quando há alterações não confirmadas nessa pasta.

    Por exemplo, uma usuária edita um arquivo em uma pasta e não confirma as alterações. Em seguida, ela tenta alterar o padrão de check-out esparso para não incluir essa pasta. Nesse caso, o padrão é aceito, mas a pasta real não é excluída. Ela precisa reverter o padrão para incluir essa pasta, confirmar as alterações e, em seguida, reaplicar o novo padrão.

Observação

Não é possível desabilitar o check-out esparso para um repositório criado com o modo de Checkout Esparso habilitado.

Fazer e efetuar push das alterações com check-out esparso

Você pode editar arquivos existentes e confirmá-los e efetuar push deles na interface da pasta Git. Ao criar novas pastas de arquivos, inclua-as no padrão de cone que você especificou para esse repositório.

Incluir uma nova pasta fora do padrão de cone resulta em um erro durante a operação de commit e push. Para corrigi-lo, edite o padrão de cone para incluir a nova pasta que você está tentando confirmar e efetuar push.

Padrões para um arquivo de configuração de repositório

O arquivo de configuração das saídas do commit usa padrões semelhantes aos padrões do gitignore e faz o seguinte:

  • Padrões positivos permitem a inclusão de saídas para notebooks correspondentes.
  • Padrões negativos desabilitam a inclusão de saídas para notebooks correspondentes.
  • Os padrões são avaliados para todos os notebooks.
  • Caminhos inválidos ou caminhos que não são resolvidos para notebooks .ipynb são ignorados.

Padrão positivo: para incluir saídas de um caminho de notebook folder/innerfolder/notebook.ipynb, use os seguintes padrões:

**/*
folder/**
folder/innerfolder/note*

Padrão negativo: para excluir saídas de um notebook, verifique se nenhum dos padrões positivos corresponde ou adicione um padrão negativo em um local correto do arquivo de configuração. Padrões negativos (exclusão) começam com !:

!folder/innerfolder/*.ipynb
!folder/**/*.ipynb
!**/notebook.ipynb

Limitação de check-out esparso

Atualmente, o check-out esparso não funciona para repositórios do Azure DevOps maiores que 4 GB.

Adicionar um repositório e conectar-se remotamente mais tarde

Para gerenciar e trabalhar com pastas Git programaticamente, use a API REST de pastas Git.