Databricks Git Folders
Git Folders connect a Databricks workspace to a Git repository on GitHub, GitLab, Azure DevOps, Bitbucket, or similar services. Teams edit notebooks and code in Databricks and track every change with version control. Git Folders were previously known as Repos, and older articles may use that name.
The Shared Document History Analogy
Imagine a team writing a report in a shared document with a full history. Every edit has an author, a date, and a note. Anyone can compare versions or go back to an earlier draft. Git gives code that same safety net. Git Folders bring the safety net into the workspace.
GIT FOLDER CONNECTION
──────────────────────────────────────────────────────────
Remote repository (GitHub, GitLab, Azure DevOps)
▲ │
push │ │ pull
│ ▼
Databricks Git Folder ◄──► Notebooks and files in the workspace
Key Git Words in Plain Language
| Word | Meaning |
|---|---|
| Repository | A project folder with its full change history |
| Clone | Make a working copy of a repository |
| Branch | A separate line of work that does not disturb the main code |
| Commit | A saved snapshot with a short message |
| Push | Send your commits to the remote repository |
| Pull | Bring new remote commits into your copy |
| Pull request | A request to review and merge a branch |
Connect a Git Provider
- Open your user settings and find the Git integration section.
- Choose your provider, such as GitHub.
- Link your account through the provider's sign-in flow or add a personal access token.
- Save the settings.
Create tokens with the narrowest permissions that your work requires, and set an expiry date.
Create a Git Folder
- Open the Workspace area and choose Create, then Git folder.
- Paste the repository URL.
- Select the provider and confirm the folder name.
- Click Create. Databricks clones the repository into the workspace.
Daily Workflow
DAILY GIT WORKFLOW
──────────────────────────────────────────────────────────
Pull latest changes
│
Create a feature branch (example: add-sales-report)
│
Edit notebooks and files
│
Commit with a clear message
│
Push the branch
│
Open a pull request ──► teammate reviews ──► merge to main
Create a Branch
Open the Git dialog from the folder menu, choose Create branch, and type a name. Use short names that describe the work, such as fix-null-orders.
Commit and Push
Select the changed files in the Git dialog, write a commit message, and click Commit and Push. Write messages that explain the reason for the change, such as "Remove duplicate rows from silver orders."
Pull Updates
Pull before you start work each day. Frequent pulls reduce merge conflicts.
Notebooks as Source Files
Git stores Databricks notebooks as source files, such as .py or .sql files with special comment markers. Reviewers read plain code changes in a pull request. Notebook outputs, such as charts and tables, stay out of the repository by default, which keeps history clean and prevents accidental data exposure.
Handle Merge Conflicts
A conflict occurs when two people change the same lines. Git pauses the merge and marks the competing versions. Open the file, decide which text to keep, and commit the resolved version. Short branches and frequent pulls keep conflicts rare.
CONFLICT EXAMPLE ────────────────────────────────────────────────────────── Main branch: WHERE amount > 100 Your branch: WHERE amount > 250 Decision needed: keep one value or agree on a new one, and commit the resolved line.
Ignore Files You Should Not Track
A .gitignore file lists files that Git skips. Add temporary files, local settings, and secrets.
# .gitignore *.log .env tmp/ __pycache__/
Example: Team Report Project
Three analysts maintain a monthly report notebook. Each analyst works on a personal branch. A pull request shows the code changes, and the team lead reviews them. After approval, a merge to main triggers the deployment process that updates the production job.
TEAM PROJECT ────────────────────────────────────────────────────────── Analyst A branch ─┐ Analyst B branch ─┼─► Pull requests ─► Review ─► main ─► production job Analyst C branch ─┘
Good Habits
- Never commit passwords, tokens, or customer data.
- Keep commits small and focused on one change.
- Protect the main branch so every change needs a review.
- Run production jobs from a reviewed branch instead of personal folders.
Key Points
- Git Folders link a workspace to a remote Git repository.
- Branches, commits, push, and pull happen from the Databricks interface.
- Notebooks save as source files, so reviewers see readable changes.
- Pull requests add review and approval before code reaches production.
- Conflicts need a human decision, and frequent pulls reduce them.
- A .gitignore file and careful tokens keep secrets out of the repository.