This document shows you how to use version control in Dataform to keep track of development.
Dataform uses Git to keep track of each change made to the files inside a repository.
In a Dataform repository, you interact directly with the Git repository.
In a connected repository, you interact with the tracking branch of the remote repository that you configured during connecting the repository.
Dataform displays version control options based on the status of changes in your development workspace. For example, Dataform displays the commit option only when there are uncommitted local changes in your workspace. When the files in your workspace are an exact copy of your default or tracking branch, Dataform displays the Workspace is up to date status.
Dataform displays the following version control options:
- Commit X change(s)
- Commit the X number of local changes in your workspace or selected changed files. Dataform displays the uncommitted changes.
- Push to default branch
- Push your committed changes to your default branch. This option is available in a Dataform repository if you have no uncommitted changes in your workspace.
- Push to
your-branch-name
- Push your committed changes to
your-branch-name
. This option is available in a repository connected to a third-party Git repository if you have no uncommitted changes in your workspace. - Pull from default branch
- Update your workspaces with recent changes from your default branch. This option is available in a Dataform repository if you have no uncommitted or unpushed committed changes in your workspace.
- Pull from
your-branch-name
- Update your workspace with recent changes from
your-branch-name
. This option is available in a repository connected to a third-party Git repository if you have no uncommitted or unpushed committed changes in your workspace. - Revert to last commit
- Restore the files in your workspace to their state from your last commit.
Before you begin
- Select or Create a repository.
- Optional: Connect your repository to a third-party Git repository.
- Select or Create a development workspace.
Required roles
To get the permissions that you need to use version control in Dataform,
ask your administrator to grant you the
Dataform Editor (roles/dataform.editor
) IAM role on workspaces.
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
Pull changes
If your development workspace is out of sync with your repository, Dataform displays the Pull option. To pull changes from your repository to your development workspace, follow these steps:
- On the Dataform page, select a repository.
- In the Development workspaces tab, select a development workspace.
- On the development workspace page, do the following:
- If you are in a Dataform repository, click Pull from default branch.
- If you are in a repository
connected to a third-party Git repository,
click Pull from
your-branch-name
.
Commit changes
After you make a change in a development workspace, Dataform displays the Commit option. You can commit all local changes or selected files.
In the New commit dialog, Dataform displays the uncommitted changes.
To commit changes from your development workspace to your repository, follow these steps:
- On the Dataform page, select a repository.
- On the repository page, select a development workspace.
- On the development workspace page, click Commit.
In the New commit pane, do the following:
- In the Add a commit message field, enter a description for your commit.
Select the changed files that you want to commit.
If you don't select any files, Dataform commits all local changes. You can filter changed files by file state, filename, and path.
Click Commit All changes, or Commit X changes.
The button name depends on your selection of files to commit.
Push changes
Dataform displays the Push option after you commit changes. To push changes from your development workspace to your repository, follow these steps:
- On the Dataform page, select a repository.
- On the repository page, select a development workspace.
- Commit changes.
- On the development workspace page, do the following:
- If you are in a Dataform repository, click Push to default branch.
- If you are in a repository
connected to a third-party Git repository,
click Push to
your-branch-name
.
Revert uncommitted changes
To revert uncommitted changes, follow these steps:
- On the Dataform page, select a repository.
- On the repository page, select a development workspace.
- Above the Files pane, click the More menu, and then select Revert to last commit.
Resolve merge conflicts
A merge conflict can happen when a local change in your development workspace is incompatible with a change that has been made to the default tracking branch of your repository. Merge conflicts usually occur when multiple users simultaneously edit the same file.
You encounter a merge conflict usually when you pull from a branch after a different user has pushed a conflicting change to the same branch. You need to resolve a merge conflict manually by editing the affected file.
The following code sample shows a merge conflict displayed in a SQLX file:
<<<<<<< HEAD
SELECT 1 as CustomerOrders
=======
SELECT 1 as Orders
>>>>>>> refs/heads/main
To resolve a merge conflict, follow these steps:
- In your development workspace, in the Files pane, select an affected file.
- Edit the file with your chosen changes.
- Commit changes.
- Optional: Push changes.
What's next
- To learn how to create a table, see Create a table.
- To learn more about Dataform, see Dataform overview.