A JupyterLab extension for version control using git
Project description
jupyterlab-git
A JupyterLab extension for version control using Git
To see the extension in action, open the example notebook included in the Binder demo.
Requirements
- JupyterLab >= 3.0 (older version available for 2.x)
- Git (version
>=2.x)
Usage
- Open the Git extension from the Git tab on the left panel
Install
To install perform the following steps, with pip:
pip install --upgrade jupyterlab jupyterlab-git
or with conda:
conda install -c conda-forge jupyterlab jupyterlab-git
Uninstall
pip uninstall jupyterlab_git
or with conda:
conda remove jupyterlab-git
Settings
UI Settings
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 totruehelps 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 tofalseallows for actions to trigger multiple concurrent Git actions. - cancelPullMergeConflict: cancel pulling changes from a remote repository if there exists a merge conflict. If set to
true, when fetching and integrating changes from a remote repository, a conflicting merge is canceled and the working tree left untouched. - 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 to
true, this setting guards against overwriting and/or losing uncommitted changes. - displayStatus: display Git extension status updates in the JupyterLab status bar. If
true, 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 tofalseshould 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 to
false(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 is
true, 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.
Server Settings
- Post git 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 in jupyter_notebook_config.json:
{
"JupyterLabGit": {
"actions": {
"post_init": ["touch dummy_init.dat"]
}
}
}
Troubleshoot
Before consulting the following list, be sure the jupyterlab_git server extension and the @jupyterlab/git frontend extension have the same version by executing the following commands:
jupyter server extension list
jupyter labextension list
If they do not match or one is missing, please reinstall 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.0Explicitly enable the server extension by running:
jupyter server extension enable --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 extension before 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 OKin the list, explicitly install the jupyter labextension by running:jupyter labextension install @jupyterlab/git
-
Contributing
If you would like to contribute to the project, please read our contributor documentation.
JupyterLab follows the official Jupyter Code of Conduct.
Development install
Note: You will need NodeJS to build the extension package.
The jlpm command is JupyterLab's pinned version of
yarn that is installed with JupyterLab. You may use
yarn or npm in lieu of jlpm below.
# Clone the repo to your local environment
git clone https://github.com/jupyterlab/jupyterlab-git.git
# Change directory to the jupyterlab_git directory
cd jupyterlab-git
# Install package in development mode
pip install -e .[dev]
pre-commit install
# Link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite
# Rebuild extension Typescript source after making changes
jlpm 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 needed
jlpm run watch
# Run JupyterLab in another terminal
jupyter 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, the jlpm 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
To execute the tests
pytest jupyterlab_git
jlpm run test
Contributors โจ
The Jupyter Git extension is part of Project 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):
This project follows the all-contributors specification. Contributions of any kind are welcomed!
To add yourself, or someone else, to this list you can either use the bot (@all-contributors please add <username> for <contributions>) or the CLI (jlpm all-contributors add <username> <contributions>).
If you manually edit the .all-contributorsrc config file, run yarn run contributors:generate.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file jupyterlab_git-0.30.0b1.tar.gz.
File metadata
- Download URL: jupyterlab_git-0.30.0b1.tar.gz
- Upload date:
- Size: 372.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.56.0 CPython/3.9.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 3cc15d70e121b34d374e6aa8243688732a5732ab22187d342638ebc7fa94bc6d |
|
| MD5 | 76f241134a2208be123cb4afff0cf08d |
|
| BLAKE2b-256 | 2dc601a50f4732c248fec0f12959428d084ef6a753baabbc7f75b4628047f63d |
File details
Details for the file jupyterlab_git-0.30.0b1-py3-none-any.whl.
File metadata
- Download URL: jupyterlab_git-0.30.0b1-py3-none-any.whl
- Upload date:
- Size: 583.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.56.0 CPython/3.9.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | d5c2daced422004643a4eab8e3a5676e204e9df32cae54674684965e2e20870f |
|
| MD5 | 63a46b95fdaae2e8ef91195af59743a7 |
|
| BLAKE2b-256 | 93784cf326c4c6f74f1ac57bedb2ef12d17e3766340857acd38398582149555e |
