# GitPlus
A JupyterLab plugin for version control of Jupyter notebooks. It can,
- Push GitHub commits from JupyterLab
- Create GitHub pull request from JupyterLab
## Demo
### Create GitHub Pull Request from JupyterLab
[](https://www.youtube.com/watch?v=yuvLgIjCq48)
### Push GitHub Commits from JupyterLab
[](https://www.youtube.com/watch?v=bmca1EBNpvI)
## Requirements
* JupyterLab 2.x or 3.x
* Git (running `git` on cmdline or terminal should work)
## Install
#### 1. Install Required Packages
```bash
pip install --upgrade jupyterlab_gitplus
jupyter labextension install @reviewnb/jupyterlab_gitplus
jupyter serverextension enable --py jupyterlab_gitplus
```
#### 2. Setup GitHub token
Tokens are required to make API calls to GitHub to push commits and create pull requests.
- Head over [developer settings on GitHub](https://github.com/settings/tokens). Click "Generate New Token".
- Select `repo` scope. Click "Generate Token". Copy the generated token.
- If `~/.jupyter/jupyter_notebook_config.py` **does not exist** then create one by running `jupyter notebook --generate-config`
- Open you Jupyter config file `~/.jupyter/jupyter_notebook_config.py` & paste the token as shown below
```bash
c.GitPlus.github_token = '<your-github-access-token>'
```
After installation, start JupyterLab normally & you should see "Git-Plus" as a new menu item at the top.
#### 3. [OPTIONAL] Only required for self-hosted ReviewNB customers
If your organization has a self-hosted ReviewNB instance running at e.g. `https://reviewnb.yourdomain.com`. You can configure
GitPlus to link users to PRs/commits at this URL instead of the default one as follows:
```python
c.GitPlus.self_hosted_reviewnb_endpoint = "https://reviewnb.yourdomain.com/"
```
## FAQ
<details>
<summary>Where is pull request (PR) opened in case of forked repositories?</summary>
<p>
If your repository is forked from another repository (parent) then PR will be created on parent repository.
</p></details>
<details>
<summary> Which is the <tt>base</tt> branch used in a pull request? </summary>
<p>
`base` branch in a PR is a branch against which your changes are compared and ultimately merged. We use repository's default branch (usually called `master`) as `base` branch of PR. We use parent repository's default branch as `base` in case of forked repo.
</p></details>
<details>
<summary>Which is the <tt>head</tt> branch used in a pull request?</summary>
<p>
`head` branch in a PR is a branch which contains the latest changes you've made. We create a new branch (e.g. `gitplus-xyz123`) as `head` branch. It only contains changes from the files you wish to include in the PR.
</p></details>
<details>
<summary>How can I edit a pull request opened with GitPlus?</summary>
<p>
You can head over to GitHub and edit the PR metadata to your liking. For pushing additional file changes to the same PR,
1. Copy the branch name from GitHub UI (e.g. `gitplus-xyz123`)
2. Checkout that branch locally
3. Make the file changes you want
4. Use push commit functionality from GitPlus to push new changes
</p></details>
<details>
<summary>Is GitPlus tied to ReviewNB in any way?</summary>
<p>
No. GitPlus is it's own open source project. The only connection with ReviewNB is that at the end of PR/Commit creation, GitPlus shows ReviewNB URL along with GitHub URL. You can safely ignore these URLs if you don't want to use ReviewNB.
It's is useful to see [visual notebook diffs](https://uploads-ssl.webflow.com/5ba4ebe021cb91ae35dbf88c/5ba93ded243329a486dab26e_sl-code%2Bimage.png) on ReviewNB instead of hard to read [JSON diffs](https://uploads-ssl.webflow.com/5ba4ebe021cb91ae35dbf88c/5c24ba833c78e57d6b8c9d09_Screenshot%202018-12-27%20at%204.43.09%20PM.png) on GitHub. [ReviewNB](https://www.reviewnb.com/) also facilitates discussion on notebooks cells.
</p></details>
<details>
<summary>What if I don't have a ReviewNB account?</summary>
<p>
No problem, everything in GitPlus will still work fine. Only the ReviewNB URLs won't work for you.
<p></details>
<details>
<summary>Can we use GitPlus with Gitlab/BitBucket or any other platforms?</summary>
<p>
No, currently we only support repositories on GitHub.
<p></details>
## Motivation
Our aim is to make notebooks a first class entity in Data science & ML teams. We can achieve this by making notebooks play well with existing tools & processes instead of building expensive proprietary platforms. Other projects in this direction are,
- [ReviewNB](https://www.reviewnb.com/) - Code review tool for Jupyter notebooks
- [treon](https://github.com/reviewnb/treon) - Easy to use test framework for Jupyter notebooks
## Roadmap
In future GitPlus will be able to,
- Pull changes from GitHub
- Switch/create branches locally
- Resolve notebook merge conflicts (without messing with underlying JSON)
## Development
### Install
The `jlpm` command is JupyterLab's pinned version of
[yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use
`yarn` or `npm` in lieu of `jlpm` below.
```bash
# Clone the repo to your local environment & install dependencies
# Link your development version of the extension with JupyterLab
jupyter labextension link .
# Run jupyterlab in watch mode in one terminal tab
jupyter lab --watch
# Watch the GitPlus source directory in another terminal tab
jlpm watch
# If you make any changes to server side extension (.py files) then reinstall it from source
pip install .
```
## Contributing
If you see any problem, open an issue or send a pull request. You can write to support@reviewnb.com for any questions.
Raw data
{
"_id": null,
"home_page": "https://github.com/ReviewNB/jupyterlab-gitplus",
"name": "jupyterlab-gitplus",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": null,
"keywords": "github, jupyter, notebook, pull request, version control, git",
"author": "Amit Rathi",
"author_email": "amit@reviewnb.com",
"download_url": "https://files.pythonhosted.org/packages/c5/f3/20d20e2c757d6560fad5a520f3e3322b9fbab821d1c4f48b3012732b75fc/jupyterlab_gitplus-0.3.4.tar.gz",
"platform": "Linux",
"description": "# GitPlus\n\nA JupyterLab plugin for version control of Jupyter notebooks. It can,\n\n- Push GitHub commits from JupyterLab\n- Create GitHub pull request from JupyterLab\n\n## Demo\n\n### Create GitHub Pull Request from JupyterLab\n\n[](https://www.youtube.com/watch?v=yuvLgIjCq48)\n\n### Push GitHub Commits from JupyterLab\n\n[](https://www.youtube.com/watch?v=bmca1EBNpvI)\n\n## Requirements\n\n* JupyterLab 2.x or 3.x\n* Git (running `git` on cmdline or terminal should work)\n\n## Install\n#### 1. Install Required Packages\n```bash\npip install --upgrade jupyterlab_gitplus\njupyter labextension install @reviewnb/jupyterlab_gitplus\njupyter serverextension enable --py jupyterlab_gitplus\n```\n\n#### 2. Setup GitHub token\nTokens are required to make API calls to GitHub to push commits and create pull requests.\n\n- Head over [developer settings on GitHub](https://github.com/settings/tokens). Click \"Generate New Token\".\n- Select `repo` scope. Click \"Generate Token\". Copy the generated token.\n- If `~/.jupyter/jupyter_notebook_config.py` **does not exist** then create one by running `jupyter notebook --generate-config`\n- Open you Jupyter config file `~/.jupyter/jupyter_notebook_config.py` & paste the token as shown below\n```bash\nc.GitPlus.github_token = '<your-github-access-token>'\n```\n\n\nAfter installation, start JupyterLab normally & you should see \"Git-Plus\" as a new menu item at the top.\n\n#### 3. [OPTIONAL] Only required for self-hosted ReviewNB customers \n\nIf your organization has a self-hosted ReviewNB instance running at e.g. `https://reviewnb.yourdomain.com`. You can configure\nGitPlus to link users to PRs/commits at this URL instead of the default one as follows:\n\n```python\nc.GitPlus.self_hosted_reviewnb_endpoint = \"https://reviewnb.yourdomain.com/\"\n```\n\n## FAQ\n<details>\n <summary>Where is pull request (PR) opened in case of forked repositories?</summary>\n <p>\n\n If your repository is forked from another repository (parent) then PR will be created on parent repository.\n</p></details>\n\n<details>\n <summary> Which is the <tt>base</tt> branch used in a pull request? </summary>\n <p>\n\n `base` branch in a PR is a branch against which your changes are compared and ultimately merged. We use repository's default branch (usually called `master`) as `base` branch of PR. We use parent repository's default branch as `base` in case of forked repo.\n</p></details>\n\n<details>\n <summary>Which is the <tt>head</tt> branch used in a pull request?</summary>\n <p>\n\n `head` branch in a PR is a branch which contains the latest changes you've made. We create a new branch (e.g. `gitplus-xyz123`) as `head` branch. It only contains changes from the files you wish to include in the PR.\n</p></details>\n\n<details>\n <summary>How can I edit a pull request opened with GitPlus?</summary>\n <p>\n\nYou can head over to GitHub and edit the PR metadata to your liking. For pushing additional file changes to the same PR,\n1. Copy the branch name from GitHub UI (e.g. `gitplus-xyz123`)\n2. Checkout that branch locally\n3. Make the file changes you want\n4. Use push commit functionality from GitPlus to push new changes\n</p></details>\n\n<details>\n <summary>Is GitPlus tied to ReviewNB in any way?</summary>\n <p>\n\n No. GitPlus is it's own open source project. The only connection with ReviewNB is that at the end of PR/Commit creation, GitPlus shows ReviewNB URL along with GitHub URL. You can safely ignore these URLs if you don't want to use ReviewNB.\n\n It's is useful to see [visual notebook diffs](https://uploads-ssl.webflow.com/5ba4ebe021cb91ae35dbf88c/5ba93ded243329a486dab26e_sl-code%2Bimage.png) on ReviewNB instead of hard to read [JSON diffs](https://uploads-ssl.webflow.com/5ba4ebe021cb91ae35dbf88c/5c24ba833c78e57d6b8c9d09_Screenshot%202018-12-27%20at%204.43.09%20PM.png) on GitHub. [ReviewNB](https://www.reviewnb.com/) also facilitates discussion on notebooks cells.\n</p></details>\n\n<details>\n <summary>What if I don't have a ReviewNB account?</summary>\n <p>\n\n No problem, everything in GitPlus will still work fine. Only the ReviewNB URLs won't work for you.\n<p></details>\n\n\n<details>\n <summary>Can we use GitPlus with Gitlab/BitBucket or any other platforms?</summary>\n <p>\n\n No, currently we only support repositories on GitHub.\n<p></details>\n\n## Motivation\nOur aim is to make notebooks a first class entity in Data science & ML teams. We can achieve this by making notebooks play well with existing tools & processes instead of building expensive proprietary platforms. Other projects in this direction are,\n\n- [ReviewNB](https://www.reviewnb.com/) - Code review tool for Jupyter notebooks\n- [treon](https://github.com/reviewnb/treon) - Easy to use test framework for Jupyter notebooks\n\n## Roadmap\nIn future GitPlus will be able to,\n\n- Pull changes from GitHub\n- Switch/create branches locally\n- Resolve notebook merge conflicts (without messing with underlying JSON)\n\n\n## Development\n\n### Install\n\nThe `jlpm` command is JupyterLab's pinned version of\n[yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use\n`yarn` or `npm` in lieu of `jlpm` below.\n\n```bash\n# Clone the repo to your local environment & install dependencies\n\n# Link your development version of the extension with JupyterLab\njupyter labextension link .\n\n# Run jupyterlab in watch mode in one terminal tab\njupyter lab --watch\n\n# Watch the GitPlus source directory in another terminal tab\njlpm watch\n\n# If you make any changes to server side extension (.py files) then reinstall it from source\npip install .\n```\n\n## Contributing\nIf you see any problem, open an issue or send a pull request. You can write to support@reviewnb.com for any questions.\n",
"bugtrack_url": null,
"license": null,
"summary": "JupyterLab extension to create GitHub pull requests",
"version": "0.3.4",
"project_urls": {
"Homepage": "https://github.com/ReviewNB/jupyterlab-gitplus"
},
"split_keywords": [
"github",
" jupyter",
" notebook",
" pull request",
" version control",
" git"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d4f838f2db13cff4fb589b311efcd09fd67a5c1e77ca156add6b7987c31928de",
"md5": "751a68dc5fb45c73ec9a52d91506db62",
"sha256": "99948e0cb60064c38c20cd1d462d7fb036cc01d8dfd0ecbfe7a7e85a64ba93ef"
},
"downloads": -1,
"filename": "jupyterlab_gitplus-0.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "751a68dc5fb45c73ec9a52d91506db62",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 168199,
"upload_time": "2024-06-25T09:23:44",
"upload_time_iso_8601": "2024-06-25T09:23:44.474463Z",
"url": "https://files.pythonhosted.org/packages/d4/f8/38f2db13cff4fb589b311efcd09fd67a5c1e77ca156add6b7987c31928de/jupyterlab_gitplus-0.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c5f320d20e2c757d6560fad5a520f3e3322b9fbab821d1c4f48b3012732b75fc",
"md5": "ec005db562db8847207a2daebd768c39",
"sha256": "d6f9e28303ac4f74b92e6a5aacd51152b6d13f717e3e0ae734d27e9d1f6fc8a8"
},
"downloads": -1,
"filename": "jupyterlab_gitplus-0.3.4.tar.gz",
"has_sig": false,
"md5_digest": "ec005db562db8847207a2daebd768c39",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 81535,
"upload_time": "2024-06-25T09:23:45",
"upload_time_iso_8601": "2024-06-25T09:23:45.982124Z",
"url": "https://files.pythonhosted.org/packages/c5/f3/20d20e2c757d6560fad5a520f3e3322b9fbab821d1c4f48b3012732b75fc/jupyterlab_gitplus-0.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-25 09:23:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ReviewNB",
"github_project": "jupyterlab-gitplus",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "jupyterlab-gitplus"
}
JSON
