创建和管理 Git 文件夹

本页介绍如何创建Azure Databricks Git 文件夹并执行常见的 Git 操作，包括克隆、分支、提交和推送。

本指南涵盖以下Git操作：

安装和配置	每日工作流	高级操作
克隆存储库使用 Git CLI 访问 Git 对话框	创建新分支切换到其他分支提交和推送更改拉取更改在 Git 文件夹中进行协作	合并分支解决合并冲突重新构建分支重置分支配置稀疏签出删除 Git 文件夹

克隆存储库

克隆远程存储库时，Databricks 会在工作区中创建一个 Git 文件夹，其中包含存储库内容并跟踪更改。可以使用 Azure Databricks UI 或 Web 终端创建 Git 文件夹。

注意

您必须在希望创建 Git 文件夹的父文件夹上具有 CAN MANAGE 的权限。
您的工作区必须配置 Git 凭据。请参阅将 Git 提供程序连接到 Databricks。

从用户界面克隆

在边栏中，选择 “工作区 ”并浏览到要在其中创建 Git 存储库克隆的文件夹。
单击“ 创建>Git”文件夹。

在“创建 Git 文件夹”对话框中提供以下信息：

领域	Description
Git 存储库 URL	要克隆的 Git 存储库的 URL，格式 `https://example.com/organization/project.git`为。
Git 服务提供商	要克隆的存储库的 Git 提供程序。
Git 文件夹名称	工作区中包含克隆存储库内容的文件夹的名称。
稀疏签出模式	是否使用稀疏签出，即使用圆锥模式仅克隆存储库中的部分目录。如果存储库超出大小限制，这非常有用。

单击“创建 Git 文件夹”。远程存储库的内容已克隆到您的工作区，您可以开始使用受支持的 Git 操作。如果工作区符合条件，则会自动使用 Git CLI 访问权限创建 Git 文件夹。请参阅 Git 文件夹何时获取 Git CLI 访问权限？

从 Web 终端克隆

还可以直接从 Web 终端创建具有 CLI 访问权限的 Git 文件夹：

访问 Web 终端。请参阅 Azure Databricks Web 终端中的 Run shell 命令。

导航到 /Workspace 的父目录。

cd /Workspace/Users/<your-email>/<project>

克隆存储库：
```
git clone <remote-url>
```
该 git clone 命令使用工作区中配置的 Git 凭据。请参阅将 Git 提供程序连接到 Databricks。
刷新浏览器以查看工作区文件浏览器中的新文件夹。

使用 Git CLI 命令

重要

此功能目前以公共预览版提供。工作区管理员可以从预览页控制对 Git 文件夹的 Git CLI 支持的访问权限。请参阅 Manage Azure Databricks 预览版。

通过 Git CLI 访问的 Git 文件夹，可以在无服务器计算、笔记本或 Web 终端上运行标准 Git 命令。您可以：

运行任何 Git 命令，包括git stash和 git push --forcegit rebase -i。
将 linting 和代码扫描与预提交挂钩集成。
使用超越标准 Git 文件夹 2 GB 内存限制和 4 GB 磁盘限制的存储库。
使用 Git 子模块和大型文件存储（LFS）。
在本地分阶段暂存多个提交记录，然后再推送到远程存储库。

Git CLI 计算要求

所需的计算取决于如何使用已启用 CLI 的 Git 文件夹：

运算	计算要求
通过 UI 创建具有 CLI 访问权限的 Git 文件夹	无服务器计算
从 Git 文件夹界面运行 Git 操作（拉取、推送、提交）	无服务器计算
从笔记本或 Web 终端运行 Git CLI 命令	无服务器计算（环境版本 5 或更高版本）或经典计算（Databricks Runtime 17.0 或更高版本）

若要启用无服务器计算，请参阅 “连接到无服务器计算”。

如果 Git 提供程序需要专用网络连接，请参阅 “配置网络连接”。

Git 文件夹何时获取 Git CLI 访问权限？

从 UI 创建 Git 文件夹时，如果工作区符合条件，Azure Databricks会自动启用 Git CLI 访问。如果工作区不符合条件，Azure Databricks改为创建标准 Git 文件夹，并且仍可以从 Git 文件夹 UI 执行 Git 操作。

从 UI 创建的 Git 文件夹可在以下所有内容都为 true 时获取 Git CLI 访问权限：

为工作区启用了 Git CLI 预览版。工作区管理员从 “预览 ”页控制这一点。请参阅 Manage Azure Databricks 预览版。
您的工作区已提供无服务器计算。请参阅连接到无服务器计算。
Azure Databricks 可以通过无服务器计算资源访问你的 Git 提供商。 Azure Databricks在克隆存储库之前验证连接。如果 Git 提供程序需要专用网络连接，请参阅 “配置网络连接”。
在公共预览版期间，存储库限制为 10,000 个文件。超过此限制的仓库将改为以标准 Git 文件夹的形式进行克隆。

从 Web 终端克隆的 Git 文件夹始终具有 Git CLI 访问权限。

使用 Git CLI 访问权限创建 Git 文件夹

若要创建具有 CLI 访问权限的 Git 文件夹，

如果使用 UI，Azure Databricks在工作区符合条件时自动创建具有 Git CLI 访问权限的 Git 文件夹。请参阅 Git 文件夹何时获取 Git CLI 访问权限？如果工作区不具备条件，Azure Databricks 会改为创建一个标准 Git 文件夹。
如果使用 Web 终端，则克隆的任何存储库都自动具有 Git CLI 访问权限。

创建具有 CLI 访问权限的 Git 文件夹后，请从 Web 终端运行任何标准 Git 命令。若要打开 Web 终端，请参阅启动 Web 终端。

cd /Workspace/Users/<your-email>/<project>/my-repo

# Interactive rebase
git rebase -i main

# Stash uncommitted changes
git stash

# Work with submodules
git submodule update --init --recursive

Git CLI 限制

具有 CLI 访问权限的 Git 文件夹具有以下限制：

Git URL 允许列表适用于从 Azure Databricks UI 运行的 Git 操作，但不会对使用 Git CLI 直接运行的 Git 命令强制实施。
可通过 Git CLI 访问的 Git 文件夹不会由 List Repos API 返回。

排查Git CLI操作问题

工作区 UI 中禁止 Git 操作：未在工作区中启用无服务器计算。仍可从 Web 终端运行 Git 命令。若要启用无服务器计算，请参阅 “连接到无服务器计算”。
终端会提示你选择凭据：Git CLI 操作会自动使用存储的工作区 Git 凭据。 Azure Databricks从远程 URL 推断 Git 提供程序，并为该提供程序使用默认凭据。如果Azure Databricks无法标识要使用的单个凭据，系统会提示你选择一个凭据。若要避免出现提示，请将 DB_GIT_CREDENTIAL_NAME 环境变量设置为要使用的凭据的名称。 Azure Databricks记住用于存储库的凭据，并重复使用该凭据。
Git 操作失败，出现权限错误：请验证您对父文件夹是否具有 CAN MANAGE 权限，以及您的工作区 Git 凭证是否有效。请参阅将 Git 提供程序连接到 Databricks。

访问 Git 对话框

从笔记本或 Azure Databricks Git 文件夹浏览器访问 Git 对话框。

在笔记本中，单击标识当前 Git 分支的笔记本名称旁边的按钮。
在 Azure Databricks Git 文件夹浏览器中，单击存储库名称旁边的 Git。

会显示一个全屏对话框，您可以在其中执行 Git 操作。

用于在 Databricks 工作区中执行 Git 操作的对话框。

当前工作分支。在此处可以选择其他分支。如果其他用户有权访问此 Git 文件夹，并且他们共享同一工作区，那么更改分支后，他们的分支也会随之更改。请参阅建议的最佳做法以避免此问题。
新建分支。
签入您当前分支的文件资产和子文件夹。
显示当前分支历史记录。
从远程 Git 存储库拉取内容。
为更改添加提交消息和可选的扩展说明。
将工作提交到工作分支，并将更新的分支推送到远程 Git 存储库。

单击 “Kebab”菜单图标，Kebab 菜单可从其他 Git 分支操作中进行选择，例如硬重置、合并或变基。

Git 对话框文件夹中的分支操作菜单。

创建新分支

若要创建新分支，请执行以下操作：

打开 Git 对话框。
单击“创建分支”。
输入新分支的名称，然后选择基分支。
单击 “创建” 。

Git 对话框新建分支。

切换到其他分支

若要切换到其他分支，请使用 Git 对话框中的分支下拉列表：

Git 对话切换到另一分支

如果未提交的更改与新分支上的代码不冲突，则当前分支上的未提交更改将延续并显示为未提交的更改。如果不打算保留未提交的更改，请在分支切换前后放弃这些更改。

删除远程分支后，分支的本地版本可以保留在关联的 Git 文件夹中长达 30 天。若要完全删除 Git 文件夹中的本地分支，请删除存储库。

重要

当新分支不包含这些资产时，切换分支可能会删除工作区资产。切换回当前分支会使用新 ID 和 URL 重新创建已删除的资产。无法撤消此更改。

如果从 Git 文件夹中共享或为资产添加书签，请先在新分支上验证资产是否存在，然后再切换。

提交和推送更改

添加新的笔记本或文件时，或者对现有笔记本或文件进行更改时，Git 文件夹 UI 会突出显示所做的更改。

Git 对话框中更改已被突出显示。

为更改添加所需的提交消息，然后单击“ 提交”和“推送 ”将更改推送到远程 Git 存储库。

如果无权提交到默认分支，请创建新分支并使用 Git 提供程序的接口创建拉取请求并将其合并到默认分支。

注意

默认情况下，当笔记本以源文件格式（.py、.scala.sql、.r）保存时，笔记本输出不会包含在提交中。有关使用 IPYNB 格式提交笔记本输出的信息，请参阅控制 IPYNB 笔记本输出项目提交。

充当角色时，在 Git 文件夹中创作

使用 RBAC 时，你承担了一个角色来访问该角色范围内的数据。若要编写读取该数据的代码，请切换到该角色，使该角色的数据访问权限生效，然后提交更改。您可以以您自己的用户身份或该角色的身份提交。这一选择决定了你的 Git 提供商如何归属提交，这需要与配置该工作流所需的工作量进行权衡。两者都依赖于角色的 Git 凭据。

Approach	归属于的提交	权衡
使用用户标识提交	你个人。	更多设置：共享 Git 文件夹，使其可在两个标识下访问，并切换回用户标识以提交。可与具有只读角色的凭据配合使用。
以该角色身份提交	职责。	更简单：你一直充当角色，不共享文件夹。提交具有角色的 Git 标识，角色的 Git 凭据必须具有写入访问权限，并由承担该角色的每个人共享。

使用您的用户身份提交

在这种方法中，你使用个人 Git 凭据进行提交，因此你的 Git 提供商会将这些提交归属于你。你只是切换到该角色，以便基于该角色可访问的数据进行编写，然后再切换回你的用户身份来提交。由于你是以该角色身份进行编写、但以你的用户身份提交更改，因此必须能在这两种身份下访问到 Git 目录。通过以下两种方式之一进行设置，这在拥有文件夹的人员和共享文件夹的方向上有所不同。

选项 1：在主文件夹中克隆并与角色共享

使用你的用户身份（不要切换角色），将该存储库克隆到主目录中的 Git 文件夹（/Workspace/Users/<your-username>/...）中。请参阅克隆存储库。克隆使用个人 Git 凭据，并且你拥有该文件夹。该角色不需要其自己的 Git 凭据才能使用此选项。
向该角色授予对该文件夹的访问权限（可以运行；如果该角色需要修改文件，则授予 可以编辑 权限），这样你就可以在充当该角色时在其中工作。
假设该角色，然后在文件夹中进行更改。该角色的数据访问权限已生效。
切换回用户标识，然后提交并推送。此次提交将使用你的个人 git_username 和 git_email。

由于将文件夹从用户标识共享到角色，因此工作区资产共享控件不会影响此选项。这些控件仅限制角色向外共享资产。

选项 2：克隆角色的主文件夹，并将其与用户标识共享

假定该角色并将存储库克隆到角色的主文件夹中的 Git 文件夹中。克隆使用角色的 Git 凭据，该凭据必须至少具有读取访问权限。
在扮演该角色时，授予您的用户身份对该文件夹的访问权限（Can Edit）。
在充当角色时进行更改。该角色的数据访问权限已生效。
切换回用户标识。由于授予了用户访问权限，因此可以访问该文件夹，因此可以使用个人凭据提交和推送。此次提交将使用你的个人 git_username 和 git_email。

由于该角色将文件夹向外共享到用户标识，因此如果角色位于工作区资产共享控件拒绝列表上，则此选项不起作用。对这些角色使用选项 1。

以该角色身份提交

采用这种方式时，你会以该角色的身份进行克隆、编写和提交。这是最简单的工作流：不共享文件夹或切换标识进行提交。这要求该角色的 Git 凭据具有写权限，因为工作区界面会在一次操作中同时执行提交和推送。

承担角色。
将存储库克隆到 Git 文件夹中。由于你充当角色，因此克隆使用角色的 Git 凭据。
进行更改，然后提交并推送。该提交记录使用了该角色的 git_username 和 git_email。

在选择此方法之前权衡这些影响：

归因在角色级别进行。 你在 Git 服务提供商中看到的提交会显示该角色的 Git 身份，而不是具体作者。 Azure Databricks 审计日志会对通过工作区 UI 进行的提交同时记录 identity_metadata.run_as（角色）和 identity_metadata.run_by（你）。这不适用于从 Web 终端中的 Git CLI 运行的原始 Git 提交，Azure Databricks不归因于单个用户。
该角色的 Git 凭据为共享且具有写权限。 承担该角色的每个人都使用同一凭据进行推送，因此，如果令牌泄露或被滥用，就可以用它以该角色的身份进行推送、删除分支或创建提交。因此，Azure Databricks 建议使用只读组 Git 凭据，并采用使用你的用户身份进行提交的方法。仅当您接受这些权衡带来的取舍时，才使用具有写入权限的凭据。请参阅令牌权限。将凭据的范围限定为角色所需的存储库。

拉取更改

若要从远程 Git 存储库拉取更改，请单击 Git 操作对话框中的“拉取”。笔记本和其他文件会自动更新到远程 Git 存储库中的最新版本。如果从远程存储库提取的更改与 Azure Databricks 中的本地更改冲突，请解决合并冲突。

重要

从上游拉取更改的 Git 操作会清除笔记本状态。请参阅传入的更改会清除笔记本状态。

在 Git 文件夹中进行协作

Azure Databricks Git 文件夹在工作区中充当嵌入的 Git 客户端，使你能够通过基于 Git 的源代码管理和版本控制进行协作。对于有效的团队协作：

每个团队成员都有自己的 Git 文件夹，这些文件夹映射到远程 Git 存储库，他们可在自己的开发分支中工作。
每个 Git 文件夹只有一个用户执行 Git 操作。在同一文件夹中执行 Git操作的多个用户可能会导致分支管理问题，例如一个用户无意间为所有人切换了分支。

若要与协作者共享 Git 文件夹配置，请执行以下作：

单击“共享”。
单击 “复制”链接以创建 Git 文件夹。
将 URL 发送给协作者。
当协作者打开 URL 时，他们会看到预填充了 Git 文件夹配置的对话框。
单击创建 Git 文件夹，将存储库克隆到他们当前工作文件夹下的个人工作区中。

合并分支

Azure Databricks Git 文件夹中的合并函数使用 git merge 将提交历史记录从一个分支合并到另一个分支。对于 Git 初学者，Databricks 建议使用合并而不是存储库，因为它不需要强制推送，也不会重写提交历史记录。

若要将一个分支合并到另一个分支，请单击 “Kebab”菜单图标。烤肉串菜单，然后选择“ 合并”。

如果存在合并冲突，请在 Git 文件夹 UI 中解决它。
如果没有冲突，合并将使用 git push 推送到远程 Git 存储库。

解决合并冲突

当 Git 无法自动协调来自不同源的相同文件行的更改（例如在拉取、重新数据库或合并作期间）时，会发生合并冲突。

若要解决合并冲突，请使用显示冲突文件和解决选项的 Git 文件夹 UI。

手动编辑文件以选择要保留的更改。
选择 “保留所有当前更改 ”或 “获取所有传入更改 ”以完全接受一个版本。
中止操作并放弃冲突的更改以重试。

显示 Git 文件夹 UI 中的合并冲突的动画 GIF

手动解决冲突

通过手动冲突解决，可以确定要接受的冲突行。直接编辑文件内容以解决冲突。

显示手动解决合并冲突的动态 GIF

要解决冲突，请选择要保留的代码行并删除所有其他代码行，包括 Git 合并冲突标记。完成后，选择“标记为已解决”。

如果在解决合并冲突时做出了错误选择，请单击“ 中止 ”以中止进程并撤消所有内容。解决所有冲突后，单击 “继续合并” 或 “继续 Rebase” 以解决冲突并完成该操作。

分支变基

Azure Databricks Git 文件夹中的 rebase 函数使用 git rebase 将更改从一个分支集成到另一个分支中，方法是在目标分支上重新应用您的提交，从而创建线性历史记录。

若要在另一个分支上重新设置分支的基数，请单击 “Kebab”菜单图标。烤肉串菜单并选择 “Rebase”，然后选择目标分支。

在变基之后，运行 Git 命令 git commit 和 git push --force 来更新远程存储库。
重新定基重写提交历史记录，这可能会导致同一存储库中工作的协作者出现版本控制问题。

重置分支

从 Git 文件夹 UI 执行 Git 重置。此操作等同于 git reset --hard 与 git push --force.

Git reset 会将分支内容和历史记录替换为另一个分支的最新状态。当编辑与上游分支冲突时，可以使用此功能，在重置到上游分支时不介意丢失这些编辑。了解更多有关 git reset --hard的信息。

重置为远程分支

在这种情况下使用 git reset：

将所选分支（例如 feature_a）重置为其他分支（例如 main）。
此外，您还将上游（远程）分支 feature_a 重置为 main。

重要

重置时，会丢失分支本地版本和远程版本中所有未提交和已提交的更改。

若要将分支重置为远程分支，请执行以下操作：

在 Git 文件夹 UI 的“分支”菜单中，选择要重置的分支。
从中选择Kebab menu icon.“重置”。烤肉串菜单。
选择要重置的分支，然后单击“ 运行 Git 重置”。

配置稀疏签出模式

稀疏签出是一种客户端设置，它允许您在Azure Databricks中克隆并仅处理远程存储库中部分目录。如果存储库的大小超过 Azure Databricks 支持的limits，此功能会显得尤为实用。

克隆新存储库时启用稀疏签出模式。启用后，无法禁用稀疏签出模式。

在“ 创建 Git 文件夹 ”对话框中，启用 稀疏签出模式。
在“锥形模式”框中，指定所需的锥形签出模式。用换行符分隔多个模式。

锥形模式的工作原理

若要了解圆锥模式在稀疏签出模式下的工作原理，请参阅下图，该图表示远程存储库结构。

未启用稀疏签出的远程存储库结构。

如果选择 稀疏签出模式，但未指定圆锥模式，则应用默认圆锥模式。这只包括根目录中的文件，没有子目录，导致存储库结构如下所示：

稀疏检出：默认锥形模式。

设置稀疏签出锥形模式为 parent/child/grandchild 将递归包含目录 grandchild 的所有内容。文件会立即包含在/parent、/parent/child和根目录中。参阅以下示意图中的目录结构：

稀疏签出：指定父-孙-子文件夹锥形模式。

注意

Git cone 模式语法不支持排除行为（!）。

修改稀疏签出设置

创建存储库后，请从设置>锥形模式>中编辑稀疏签出锥形模式。

注意以下行为：

如果不存在未提交的更改，则从圆锥模式中删除文件夹会将其从Azure Databricks中删除。
通过编辑稀疏检出锥形模式添加文件夹会将其添加到 Azure Databricks 而不需要额外的拉取操作。
如果文件夹中存在未提交的更改，则无法更改稀疏签出模式以删除该文件夹。

例如，如果编辑文件夹中的文件且未提交更改，请尝试更改稀疏签出模式以排除该文件夹，则会接受该模式，但不会删除该文件夹。需要还原模式以包含该文件夹、提交更改，然后重新应用新模式。

使用稀疏签出的方式进行更改

编辑现有文件，并从 Git 文件夹提交并推送它们。创建新文件夹时，请将它们包含在为该存储库指定的锥形模式中。

在锥形模式之外包含新文件夹会导致执行提交和推送操作期间出错。若要修复此问题，请编辑圆锥模式以包含尝试提交和推送的新文件夹。

稀疏签出限制

稀疏签出不适用于大于 4 GB 的Azure DevOps存储库。
无法为启用了稀疏签出的存储库禁用稀疏签出。

以编程方式管理 Git 文件夹

若要使用 API 管理 Git 文件夹，请参阅 Repos API 参考。

删除 Git 文件夹

若要从工作区中删除 Git 文件夹，请执行以下作：

右键单击 Git 文件夹，然后选择 “移动到回收站”。
单击“ 确认”并移动到回收站。

后续步骤

设置身份验证以将 Azure Databricks 连接到您的 Git 提供商。请参阅将 Git 提供程序连接到 Databricks。
了解 Git 文件夹的大小限制和其他约束。请参阅 Azure Databricks Git 文件夹限制和参考。
为 Git 集成配置工作区级设置。请参阅 Git 目录集成配置。

Last updated on 2026-09-11