Merge pull request #706 from fcollonval/auto-backport-of-pr-630-on-0.11.x

Backport PR #630 UI feedback of Git execution

Author: fcollonval

README.md

@@ -32,10 +32,14 @@ jupyter lab build
 
 Once installed, extension behavior can be modified via the following settings which can be set in JupyterLab's advanced settings editor:
 
--   **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.
--   **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.
--   **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.
+- **blockWhileCommandExecutes**: suspend JupyterLab user interaction until Git commands (e.g., `commit`, `pull`, `reset`, `revert`) finish executing. Setting this to `true` 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 to `false` 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 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 to `false` 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.
+- **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.
 
 ### Troubleshooting
 

package.json

@@ -62,6 +62,8 @@
     "@jupyterlab/ui-components": "^1.1.0",
     "@material-ui/core": "^4.8.2",
     "@material-ui/icons": "^4.5.1",
+    "@material-ui/lab": "^4.0.0-alpha.54",
+    "@phosphor/collections": "^1.2.0",
     "@phosphor/widgets": "^1.8.0",
     "diff-match-patch": "^1.0.4",
     "nbdime": "~5.0.1",

schema/plugin.json

@@ -5,6 +5,12 @@
   "description": "jupyterlab-git settings.",
   "type": "object",
   "properties": {
+    "blockWhileCommandExecutes": {
+      "type": "boolean",
+      "title": "Suspend user interaction until commands finish",
+      "description": "Suspend JupyterLab user interaction until Git commands (e.g., commit, pull, reset, revert) finish executing. Setting this to true 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 to false allows for actions to trigger multiple concurrent Git actions.",
+      "default": true
+    },
     "cancelPullMergeConflict": {
       "type": "boolean",
       "title": "Cancel pull merge conflict",
@@ -17,10 +23,16 @@
       "description": "Disable all branch operations (new, switch) when there are changed/staged files",
       "default": false
     },
+    "displayStatus": {
+      "type": "boolean",
+      "title": "Display Git status updates",
+      "description": "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 to false should reduce visual noise.",
+      "default": true
+    },
     "doubleClickDiff": {
       "type": "boolean",
       "title": "Show diff on double click",
-      "description": "If true, doubling clicking a file in the list of changed files will open a diff",
+      "description": "If true, doubling clicking a file in the list of changed files will open a diff.",
       "default": false
     },
     "historyCount": {

src/gitMenuCommands.ts renamed to src/commandsAndMenu.ts

@@ -9,10 +9,23 @@ import {
 import { ISettingRegistry } from '@jupyterlab/coreutils';
 import { FileBrowser } from '@jupyterlab/filebrowser';
 import { ITerminal } from '@jupyterlab/terminal';
+import { CommandRegistry } from '@phosphor/commands';
+import { Menu } from '@phosphor/widgets';
 import { IGitExtension } from './tokens';
+import { GitCredentialsForm } from './widgets/CredentialsBox';
 import { doGitClone } from './widgets/gitClone';
 import { GitPullPushDialog, Operation } from './widgets/gitPushPull';
-import { GitCredentialsForm } from './widgets/CredentialsBox';
+
+const RESOURCES = [
+  {
+    text: 'Set Up Remotes',
+    url: 'https://www.atlassian.com/git/tutorials/setting-up-a-repository'
+  },
+  {
+    text: 'Git Documentation',
+    url: 'https://git-scm.com/doc'
+  }
+];
 
 /**
  * The command IDs used by the git plugin.
@@ -210,6 +223,52 @@ export function addCommands(
   });
 }
 
+/**
+ * Adds commands and menu items.
+ *
+ * @private
+ * @param app - Jupyter front end
+ * @param gitExtension - Git extension instance
+ * @param fileBrowser - file browser instance
+ * @param settings - extension settings
+ * @returns menu
+ */
+export function createGitMenu(commands: CommandRegistry): Menu {
+  const menu = new Menu({ commands });
+  menu.title.label = 'Git';
+  [
+    CommandIDs.gitInit,
+    CommandIDs.gitClone,
+    CommandIDs.gitPush,
+    CommandIDs.gitPull,
+    CommandIDs.gitAddRemote,
+    CommandIDs.gitTerminalCommand
+  ].forEach(command => {
+    menu.addItem({ command });
+  });
+
+  menu.addItem({ type: 'separator' });
+
+  menu.addItem({ command: CommandIDs.gitToggleSimpleStaging });
+
+  menu.addItem({ command: CommandIDs.gitToggleDoubleClickDiff });
+
+  menu.addItem({ type: 'separator' });
+
+  const tutorial = new Menu({ commands });
+  tutorial.title.label = ' Help ';
+  RESOURCES.map(args => {
+    tutorial.addItem({
+      args,
+      command: CommandIDs.gitOpenUrl
+    });
+  });
+
+  menu.addItem({ type: 'submenu', submenu: tutorial });
+
+  return menu;
+}
+
 /* eslint-disable no-inner-declarations */
 namespace Private {
   /**

src/components/Alert.tsx

@@ -0,0 +1,127 @@
+import * as React from 'react';
+import Portal from '@material-ui/core/Portal';
+import Snackbar from '@material-ui/core/Snackbar';
+import Slide from '@material-ui/core/Slide';
+import { default as MuiAlert } from '@material-ui/lab/Alert';
+import { Severity } from '../tokens';
+
+/**
+ * Returns a React component for "sliding-in" an alert.
+ *
+ * @private
+ * @param props - component properties
+ * @returns React element
+ */
+function SlideTransition(props: any): React.ReactElement {
+  return <Slide {...props} direction="up" />;
+}
+
+/**
+ * Interface describing component properties.
+ */
+export interface IAlertProps {
+  /**
+   * Boolean indicating whether to display an alert.
+   */
+  open: boolean;
+
+  /**
+   * Alert message.
+   */
+  message: string;
+
+  /**
+   * Alert severity.
+   */
+  severity?: Severity;
+
+  /**
+   * Alert duration (in milliseconds).
+   */
+  duration?: number;
+
+  /**
+   * Callback invoked upon clicking on an alert.
+   */
+  onClick?: (event?: any) => void;
+
+  /**
+   * Callback invoked upon closing an alert.
+   */
+  onClose: (event?: any) => void;
+}
+
+/**
+ * React component for rendering an alert.
+ */
+export class Alert extends React.Component<IAlertProps> {
+  /**
+   * Returns a React component for rendering an alert.
+   *
+   * @param props - component properties
+   * @returns React component
+   */
+  constructor(props: IAlertProps) {
+    super(props);
+  }
+
+  /**
+   * Renders the component.
+   *
+   * @returns React element
+   */
+  render(): React.ReactElement {
+    let duration: number | null = null;
+
+    const severity = this.props.severity || 'info';
+    if (severity === 'success') {
+      duration = this.props.duration || 5000; // milliseconds
+    }
+    return (
+      <Portal>
+        <Snackbar
+          key="git:alert"
+          open={this.props.open}
+          anchorOrigin={{
+            vertical: 'bottom',
+            horizontal: 'right'
+          }}
+          autoHideDuration={duration}
+          TransitionComponent={SlideTransition}
+          onClick={this._onClick}
+          onClose={this._onClose}
+        >
+          <MuiAlert variant="filled" severity={severity}>
+            {this.props.message || '(missing message)'}
+          </MuiAlert>
+        </Snackbar>
+      </Portal>
+    );
+  }
+
+  /**
+   * Callback invoked upon clicking on an alert.
+   *
+   * @param event - event object
+   */
+  private _onClick = (event: any): void => {
+    if (this.props.onClick) {
+      this.props.onClick(event);
+      return;
+    }
+    this._onClose(event, 'click');
+  };
+
+  /**
+   * Callback invoked upon closing an alert.
+   *
+   * @param event - event object
+   * @param reason - reason why the callback was invoked
+   */
+  private _onClose = (event: any, reason: string): void => {
+    if (reason === 'clickaway') {
+      return;
+    }
+    this.props.onClose(event);
+  };
+}