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 (version 1.x or 2.x)
• Git (version>=2.x)

• Open the Git extension from theGit tab on the left panel

To install perform the following steps, withpip:

pip install --upgrade jupyterlab jupyterlab-gitjupyter lab build

or withconda:

conda install -c conda-forge jupyterlab jupyterlab-gitjupyter lab build

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.
• 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.

• 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.

In~/.jupyter/jupyter_notebook_config.py:

c.JupyterLabGit.actions= {"post_init": ["touch dummy_init.dat"]}

Or equivalently injupyter_notebook_config.json:

{"JupyterLabGit": {"actions": {"post_init": ["touch dummy_init.dat"      ]    }  }}

Before consulting the following list, be sure thejupyterlab_git server extension and the@jupyterlab/git frontend extension have the same version by executing the following commands:

jupyter serverextension listjupyter labextension list

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

• Issue: the Git panel does not recognize that you are in a Git repository.

  Possible fixes:

  • Be sure to be in a Git repository in the filebrowser tab

  • Check the server log. If you see a warning with a 404 code similar to:[W 00:27:41.800 LabApp] 404 GET /git/settings?version=0.20.0

    Explicitly enable the server extension by running:

    jupyter serverextensionenable --py jupyterlab_git

  • If you are using JupyterHub or some other technologies requiring an initialization script which includes the jupyterlab-git extension, be sure to install both the frontend and the server extensionbefore launching JupyterLab.

• Issue: the Git panel is not visible.

  Possible fixes:

  • Check that the JupyterLab extension is installed:

    jupyter labextension list

    If you don't see@jupyterlab/git v... enabled OK in the list, explicitly install the jupyter labextension by running:

    jupyter labextension install @jupyterlab/git

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

JupyterLab follows the officialJupyter Code of Conduct.

Requires NodeJS

# Install new-ish JupyterLabpip install -U jupyterlab# Clone the repo to your local environment, ensure the git branch name is jlab-2git clone -b jlab-2 https://github.com/jupyterlab/jupyterlab-git.gitcd jupyterlab-git# Install the server extension in development mode and enable itpip install -e .[test]pre-commit installjupyter serverextensionenable --py jupyterlab_git --sys-prefix# Build and install your development version of the extensionjlpmjupyter labextension install.

To rebuild the package after a change and the JupyterLab app:

jlpm run buildjupyter lab build

To continuously monitor the project for changes and automatically trigger a rebuild, start Jupyter in watch mode:

jupyter lab --watch

And in a separate session, begin watching the source directory for changes:

jlpm run watch

Now every change will be built locally and bundled into JupyterLab. Be sure to refresh your browser page after saving file changes to reload the extension (note: you'll need to wait for webpack to finish, which can take 10s+ at times).

To execute the tests

pytest jupyterlab_gitjlpm runtest

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):

Brian E. Granger 📆🎨🤔🔍	Saul Shanabrook 💻📆👀🚇	Jaipreet Singh 📆👀💻🎨	Frédéric Collonval 🚧	jupytercalpoly 🤝	Amazon Web Services 🤝	The D. E. Shaw Group 🤝
Ji Zhang 💻👀	Hana Zarea 💻👀	Noah Stapp 💻👀	Ashutosh Bondre 💻👀	Neelam Gehlot 💻👀	Konstantin Taletskiy 💻👀	Max Klein 💻👀📆🎨🚇
Athan 💻👀📆🎨	Ian Hunt-Isaak 💻👀

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.