Using Version Control and Deploying

On this Page
Docs Menu

Looker provides a development mode to let you develop your model in a safe environment that will not impact other users — until you are ready to deploy your changes.

Git Integration for Version Control

Looker generally uses GitHub for LookML source file management. However Looker also can be configured to work with other Git providers such as GitLab, Bitbucket, or any Git server that can use an SSH key for authentication.

Looker uses Git to record changes and manage file versions. Each LookML project corresponds with a Git repository, and each user’s development mode correlates to a Git branch. Git repositories are often called “repos”.

This page assumes that your project has already been set up for version control. If you see a Configure Git button instead of the choices described on this page, you need to first set up Git for your project.

Executing Git Commands in Looker

Looker has a built-in interface that integrates with your Git service. In the LookML IDE, you’ll see a button in the upper left for Git:

The Git button shows different options, depending on where you are in the process of making changes and deploying to your production mode. In general, the option shown on the button is the best guide for your next action.

The Git button also has a dropdown menu, from which you can execute additional commands. (The commands available on the dropdown menu depend on where you are in the process of making changes and deploying to your production mode.) For example:

If your development mode is in sync with production mode, you will see the Up-to-Date with Production message instead of a Git button. In this case, you can still use the Git dropdown menu:

Finally, experienced Git users can access additional options for the Git menu by holding down the shift button while clicking the Git menu:

Getting Your Changes to Production

To give business users access to your changes, you need to commit the changes and then deploy to production. Before committing, you may want to first review the uncommitted changes.

If you see a Configure Git button instead of the choices described in this section, you need to first set up Git for your project.

View Uncommitted Changes

Once you have saved changes to your files, you can review all of your changes before committing them by using the View Uncommitted Changes option from the Git dropdown menu:

In the Uncommitted Changes to Project window, you can see a summary of all of the uncommitted, saved changes in all of the project’s files. For each change, Looker shows the following:

  • The name of the file replaced and the name of the file added.
    • The name of the file replaced is indicated with “---”) and the name of the file added (indicated with “+++”). In many cases this may show different versions of the same file, with revisions identified by --- a/ and +++ b/.
    • Deleted files are shown as replacing a null file (+++ /dev/null).
    • Added files are shown as replacing a null file (--- /dev/null).
  • The line number where the change begins.

    For example, -101,4 +101,4 indicates that at the 101st line in the file, 4 lines were removed and 4 lines were added. A deleted file with 20 lines would show -1,20 +0,0 to indicate that at the first line in the file, 20 lines were removed and replaced by zero lines.
  • The text that was updated.
    • Deleted lines are displayed in red.
    • Added lines are shown in green.

The LookML IDE also has several indicators are always displayed when you are in Development Mode and have uncommitted changes, as described on this page.

Commit Changes

After you have made and saved any changes to your LookML project, the Git button displays the following message:

If desired, you can first review your uncommitted changes before committing.

When you are ready to commit the changes, use the Commit Changes button to commit these changes to your development mode. The following window displays, listing the files that have been added, changed, or deleted.

Enter a message to briefly describe your changes and uncheck any files you don’t want included in the sync. Then click Commit to commit the changes.

Deploy to Production

If you want to push your committed changes to the Production mode so that other users can see them, click Deploy to Production.

Checking the Impact of Your Changes

After making your changes available to the organization you can use content validation check to make sure you have not invalidated any dashboards or saved Looks. You’ll have the opportunity to fix them if you have.

Handling Typical Issues

While working on your model, you may need to:

  • Abandon your changes

    Occasionally you may want to abandon your data modeling changes. If they are not yet saved, you can simply refresh or navigate away from the page, then accept the warning prompt. If you have saved them, you can revert the uncommitted changes as described below.

  • Handle merge conflicts with other developers’ work

    If you have more than one developer working on your data model, Git typically handles the situation. However, occasionally Git needs a human to resolve merge conflicts.

Some changes, such as changing the name of a field, can affect existing dashboards and Looks. As mentioned earlier, after making your changes available to the organization you can use content validation to check your content and fix any issues.

Revert Uncommitted Changes

If you do not want to deploy your saved changes, you can revert all of the uncommitted changes for all files in the project or just text changes in a single file.

To revert uncommitted changes for all files, use the Revert Uncommitted Changes option from the Git menu:

To undo the deletion or renaming of a file, you must use this Revert Uncommitted Changes option to revert all uncommitted changes.

To revert any additions or deletions in the contents of a single file, select the Revert Changes option from the file’s gear menu:

Resolving Merge Conflicts

A merge conflict occurs when Git cannot automatically merge your new changes with the production version of your LookML files. This usually occurs when another developer has made changes since you last pulled, and Git cannot automatically choose which changes to keep.

If you have a merge conflict in your code, you will be warned in Looker after you commit changes and then pull from production. It is crucial to not push changes until you have resolved the merge conflict. Pushing a merge conflict to production will cause parse errors that may prevent exploration of your data.

If you get a merge conflict, instructions to resolve it are found in this article.

All Available Git Commands

This table describes all of the Git commands and shows the ways you can access each command:

Function Description How to Access
Configure Git If you have just created a project, you will need to configure Git for the project. See this page for information on connecting Looker to a Git repository. Button
Test Git Connection ADDED4.20Once you have configured Git for your project, you can use the Test Git Connection option to run the Git Test Connection tool to verify that the Git connection is set up properly. See this page. Button,
Shift-click Git menu
Validate LookML If you have saved changes to your files, you will see the Validate LookML button. Click the button to start LookML validation of your model. See this page for more information. Button
View Uncommitted Changes If you have saved changes that you have not yet committed, you can use the View Uncommitted Changes option to see all of the changes that you have saved since your last commit. See this section for more information. Regular Git menu,
Shift-click Git menu
Revert Uncommitted Changes If you have saved changes that you have not yet committed, you can use the Revert Uncommitted Changes option to discard all of the changes that have not been committed. See this section for more information. Regular Git menu,
Shift-click Git menu
Revert to Production The Revert to Production option discards any changes in your development mode and syncs your development mode to the current production mode. Note that this has two effects:
  1. Discards any of your committed and uncommitted changes that have not been deployed to production.
  2. Updates your development mode with any changes that other users have made to the current production mode.
Regular Git menu,
Shift-click Git menu
Commit Changes After you have made and saved any changes to your LookML project, use the Commit Changes option to commit these changes to your local development mode. See this section for more information. Button,
Shift-click Git menu
Deploy to Production After you have committed changes, use the Deploy to Production option to update the production branch with the committed changes from your development branch. Button,
Shift-click Git menu
Sync Development Mode If you have made changes to your local developer branch that are not present on the remote developer branch, you will see the Sync Development Mode button. Clicking the button will sync changes from your local developer branch to the remote developer branch. Button
Pull Development Mode If there are changes to your developer branch on the remote end and your local development branch needs to be updated, you will see the Pull Development Mode button. Clicking the button will pull any changes from the remote developer branch and add them to your local developer branch. (This is a rare case, so you may never see this button.) Button
History Click the History menu option to see a list of the commits to your development branch, which includes all of the commits that you have pulled into your development branch from the production branch (including commits from other users). If the Git Project Settings (listed in this table) has GitHub Integration (or the equivalent for your Git provider) enabled, each of the commits will include a link to the commit on your Git provider so you can view the exact changes. You will need an account on the Git provider in order to open the links. Regular Git menu,
Shift-click Git menu
Project Settings Opens the Project Settings window, where you can reset the Git provider connection and configure such settings as the project name, LookML validation requirements, and integration with the Git provider. Regular Git menu,
Shift-click Git menu
For Projects Where Pull Requests are Recommended or Required
(see this article for information on setting up Git with pull requests)
Open Pull Request The Open Pull Request option will open a new browser window to your Git provider’s new pull request page. From there you can create a pull request for your developer branch.
NOTE: Until the pull request is approved and/or closed, all future commits on the branch will be included in the same pull request.
Button
Open Pull Request on GitHub The Open Pull Request on GitHub option will open a new browser window to your Git provider’s new pull request page. From there you can create a pull request for your developer branch.
NOTE: Until the pull request is approved and/or closed, all future commits on the branch will be included in the same pull request.
Shift-click Git menu
Open Project on GitHub The Open Project on GitHub option opens a browser window to the GitHub project files. Shift-click Git menu
For Advanced Git Users Only
Pull from Production The Pull from Production option will pull the current state of the remote production branch and merge it into your local developer branch, and then push the current local developer branch to the remote developer branch. Button,
Regular Git menu,
Shift-click Git menu
Pull from Developer Branch The Pull from Developer Branch option retrieves the most recent versions of any changed files to your developer branch on the remote end and syncs them to your local development mode. (This is a rare case.) Shift-click Git menu
Push to Developer Branch If the current, committed changes on the local developer branch are ahead of the remote developer branch, use the Push to Developer Branch option push the changes from your local developer branch to the remote developer branch. Shift-click Git menu
Still have questions?
Go to Discourse - or - Email Support
Top