Repository files navigation

A JupyterLab extension for version control using Git

To see the extension in action, open the example notebook included in the Binderdemo.

• JupyterLab >= 4.0 ([older version] available for 2.x and 3.x)
• Git (version>=2.x)

For older versions of JupyterLab, go to:

• 3.x branch
• 2.x branch

• Open the Git extension from theGit tab on the left panel
• Set up authentication

To install perform the following steps, withpip:

pip install --upgrade jupyterlab jupyterlab-git

or withconda:

conda install -c conda-forge jupyterlab jupyterlab-git

To remove the extension, execute:

pip uninstall jupyterlab-git

or withconda:

conda remove jupyterlab-git

If you are seeing errors similar to[E yyyy-mm-dd hh:mm:ss ServerApp] 500 POST /git/<clone|push|pull|status> on the console which is running the JupyterLab server, you probably need to set up a credentials store for your local Git repository.

This extension tries to handle credentials for HTTP(S) connections (if you don't have set up a credential manager). But not for other SSH connections.

For Windows users, it is recommended to installgit for windows. It will automatically set up a credential manager.In order to connect to a remote host, it is recommended to use SSH.

The extension can cache temporarily (by default for an hour) credentials. To use the caching, you will need tocheck the optionSave my login temporarily in the dialog asking your credentials.

You can set a longer cache timeout; seeServer Settings.

This is a new feature since v0.37.0

Here are the steps to follow to set up SSH authentication (skip any that is already accomplished for your project):

1. Create a SSH key
2. Register the public part of it to your Git server:
   • GitHub
   • GitLab
3. Optionally, if you have more than one key managed by your ssh agent:Create a config file for the ssh-agent
4. Tell your local Git repository toconnect to remote via ssh

You should now be able to pull and push committed changes to and from your remote repository using the respective buttons on the top of the extension's panel.

Once installed, extension behavior can be modified via the following settings which can be set in JupyterLab's advanced settings editor:

• blockWhileCommandExecutes: suspend JupyterLab user interaction until Git commands (e.g.,commit,pull,reset,revert) finish executing. Setting this totrue helps mitigate potential race conditions leading to data loss, conflicts, and a broken Git history. Unless running a slow network, UI suspension should not interfere with standard workflows. Setting this tofalse allows for actions to trigger multiple concurrent Git actions.
• cancelPullMergeConflict: cancel pulling changes from a remote repository if there exists a merge conflict. If set totrue, when fetching and integrating changes from a remote repository, a conflicting merge is canceled and the working tree left untouched.
• commitAndPush: Whether to trigger or not a push for each commit; default isfalse.
• disableBranchWithChanges: disable all branch operations, such as creating a new branch or switching to a different branch, when there are changed/staged files. When set totrue, this setting guards against overwriting and/or losing uncommitted changes.
• displayStatus: display Git extension status updates in the JupyterLab status bar. Iftrue, the extension displays status updates in the JupyterLab status bar, such as when pulling and pushing changes, switching branches, and polling for changes. Depending on the level of extension activity, some users may find the status updates distracting. In which case, setting this tofalse should reduce visual noise.
• doubleClickDiff: double click a file in the Git extension panel to open a diff of the file instead of opening the file for editing.
• historyCount: number of commits shown in the history log, beginning with the most recent. Displaying a larger number of commits can lead to performance degradation, so use caution when modifying this setting.
• promptUserIdentity: Whether to prompt for user name and email on every commit.
• refreshIfHidden: whether to refresh even if the Git tab is hidden; default tofalse (i.e. refresh is turned off if the Git tab is hidden).
• refreshInterval: number of milliseconds between polling the file system for changes. In order to ensure that the UI correctly displays the current repository status, the extension must poll the file system for changes. Longer polling times increase the likelihood that the UI does not reflect the current status; however, longer polling times also incur less performance overhead.
• simpleStaging: enable a simplified concept of staging. When this setting istrue, all files with changes are automatically staged. When we develop in JupyterLab, we often only care about what files have changed (in the broadest sense) and don't need to distinguish between "tracked" and "untracked" files. Accordingly, this setting allows us to simplify the visual presentation of changes, which is especially useful for those less acquainted with Git.

• JupyterLabGit.actions.post_init: Set postgit init actions.It is possible to provide a list of commands to be executed in a folder after it is initialized as Git repository.
• JupyterLabGit.credential_helper: Git credential helper to set to cache the credentials.The default value iscache --timeout=3600 to cache the credentials for an hour. If you want to cache them for 10 hours, setcache --timeout=36000.
• JupyterLabGit.excluded_paths: Set path patterns to exclude from this extension. You can use wildcard and interrogation mark for respectively everything or any single character in the pattern.
• JupyterLabGit.git_command_timeout_s: Set the timeout for git operations. Defaults to 20 seconds.

c.JupyterLabGit.actions= {"post_init": ["touch dummy_init.dat"]}c.JupyterLabGit.credential_helper='cache --timeout=3600'

{"JupyterLabGit": {"actions": {"post_init": ["touch dummy_init.dat"]    },"credential_helper":"cache --timeout=3600"  }}

If you are seeing the frontend extension, but it is not working, checkthat the server extension is enabled:

jupyter server extension list

If the server extension is installed and enabled, but you are not seeingthe frontend extension, check the frontend extension is installed:

jupyter labextension list

If they do not match or one is missing, pleasereinstall the package.

If you would like to contribute to the project, please read ourcontributor documentation.

JupyterLab follows the officialJupyter Code of Conduct.

Note: You will need NodeJS to build the extension package.

Thejlpm command is JupyterLab's pinned version ofyarn that is installed with JupyterLab. You may useyarn ornpm in lieu ofjlpm below.

# Clone the repo to your local environmentgit clone https://github.com/jupyterlab/jupyterlab-git.git# Change directory to the jupyterlab-git directorycd jupyterlab-git# Install package in development modepip install -e".[dev,test]"pre-commit install# Link your development version of the extension with JupyterLabjupyter labextension develop. --overwrite# Server extension must be manually installed in develop modejupyter server extensionenable jupyterlab_git# Rebuild extension Typescript source after making changesjlpm run build

You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.

# Watch the source directory in one terminal, automatically rebuilding when neededjlpm run watch# Run JupyterLab in another terminaljupyter lab

With the watch command running, every saved change will immediately be built locally and available in your running JupyterLab. Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the extension to be rebuilt).

By default, thejlpm run build command generates the source maps for this extension to make it easier to debug using the browser dev tools. To also generate source maps for the JupyterLab core extensions, you can run the following command:

jupyter lab build --minimize=False

# Server extension must be manually disabled in develop modejupyter server extension disable jupyterlab_gitpip uninstall jupyterlab_git

In development mode, you will also need to remove the symlink created byjupyter labextension developcommand. To find its location, you can runjupyter labextension list to figure out where thelabextensionsfolder is located. Then you can remove the symlink named@jupyterlab/git within that folder.

This extension is usingPytest for Python code testing.

Install test dependencies (needed only once):

pip install -e".[test]"# Each time you install the Python package, you need to restore the front-end extension linkjupyter labextension develop. --overwrite

To execute them, run:

pytest -vv -r ap --cov jupyterlab_git

This extension is usingJest for JavaScript code testing.

To execute them, execute:

jlpmjlpmtest

This extension usesPlaywright for the integration tests (aka user level tests).More precisely, the JupyterLab helperGalata is used to handle testing the extension in JupyterLab.

More information are provided within theui-tests README.

SeeRELEASE

The Jupyter Git extension is part ofProject Jupyter and is developed by an open community of contributors. To see who has been active recently, please look at the"Contributors" tab. Below we list the people and entities who contributed in different ways to the project (emoji key):

Amazon Web Services 🤝	Ashutosh Bondre 💻👀	Athan 💻👀📆🎨	Ben Asokanthan 💻	Bosco Chan 💻	Brian E. Granger 📆🎨🤔🔍	Daman Arora 💻
Dat Quach 💻	Frédéric Collonval 🚧	Hana Zarea 💻👀	Ian Hunt-Isaak 💻👀	Jaipreet Singh 📆👀💻🎨	Ji Zhang 💻👀	Kentaro Lim 💻
Konstantin Taletskiy 💻👀	Kostya Farber 💻	Linda Ngoc Nguyen 💻	Major League Hacking 🤝	Max Klein 💻👀📆🎨🚇	Michał Krassowski 💻👀🐛	Navinn Ravindaran 💻
Neelam Gehlot 💻👀	Noah Stapp 💻👀	Saul Shanabrook 💻📆👀🚇	Shawn Esquivel 💻	Sheeza Aziz 💻	Sina Khalili 💻	The D. E. Shaw Group 🤝
Zeshan Fayyaz 💻	Zong Xun 💻	jupytercalpoly 🤝

This project follows theall-contributors specification. Contributions of any kind are welcomed!

To add yourself, or someone else, to this list you can eitheruse the bot (@all-contributors please add <username> for <contributions>) orthe CLI (jlpm all-contributors add <username> <contributions>).

If you manually edit the.all-contributorsrc config file, runyarn run contributors:generate.