Improve support for selecting and downloading changes

A new interactive function called `gerrit-download-and-open-overview'
was added which downloads the change and opens an magit-commit buffer
using `magit-show-commit'. (It the downloaded change is at the top of a
relation chain, the other commits are currently not displayed by this
`gerrit-download-and-open-overview' function.

Closes: #19
Change-Id: Ie3ed04a8f212cb8c0a98745d1dca4f680f420642

gerrit.el

@@ -159,6 +159,18 @@ gerrit-download is used."
   "'project (the project name)"
   )
 
+;; TODO document this variable
+;; (setq gerrit-project-to-local-workspace-alist
+;;   '(
+;;     (("software/pro1" . "branch1") . "~/sandbox/pro1")
+;;     (("software/pro2" . "branch2") . "~/sandbox/pro2")
+;;   ))
+(defvar gerrit-project-to-local-workspace-alist nil)
+
+;; TODO docs missing
+;; mention (project:A OR project:B OR project:C)
+(defvar gerrit-interesting-open-changes-filter "is:open")
+
 (defun gerrit-download-format-change (change)
   (let (columns)
     ;; can this be implemented in an easier way?
@@ -215,6 +227,7 @@ This refspec is a string of the form 'refs/changes/xx/xx/x'.
     ;; (e.g. if ssh-add was not called) this async call runs
     ;; magit-process-password-prompt-regexps (used in magit-process-filter)
     ;; which is called in magit-start-process
+    ;; (see https://github.com/magit/magit/issues/4323)
     (magit-run-git-async "fetch"
                          (gerrit-get-remote)
                          (gerrit-download--get-refspec change-metadata))
@@ -1215,6 +1228,7 @@ gerrit-upload: (current cmd: %(concat (gerrit-upload-create-git-review-cmd)))
 
 (defun gerrit--select-change-from-matching-changes (search-string)
   ;; see https://gerrit-review.googlesource.com/Documentation/user-search.html
+  ;; clients can let-bind `gerrit-change-singleline-columns'
   (let* ((open-changes (seq-map #'reviewgerrit-download-format-change
                                 (gerrit-rest-change-query
                                  (or search-string "is:open")
@@ -1228,15 +1242,49 @@ gerrit-upload: (current cmd: %(concat (gerrit-upload-create-git-review-cmd)))
   "Download change with CHANGENR from the gerrit server."
   (interactive
    (list
-    (gerrit--select-change-from-matching-changes
-     (concat "status:open project:"
-             (gerrit-get-current-project)))))
+    (let
+        ((gerrit-change-singleline-columns '(number branch project subject)))
+      (gerrit--select-change-from-matching-changes
+       (concat "status:open project:"
+               (gerrit-get-current-project))))))
 
   (gerrit--init-accounts)
   (if gerrit-use-gitreview-interface
       (gerrit-download--gitreview changenr)
     (gerrit-download--new changenr)))
 
+;; TODO split this up into two parts (one that downloads the change and one that opens the overview page using magit-show-commit
+(defun gerrit-download-and-open-overview (changenr)
+  ;; since a simple "is:open" query might return a lot of gerrit-changes, it
+  ;; is possible to filter the returned results by setting an variable
+  ;; called `gerrit-interesting-open-changes-filter'.
+  (interactive (list
+                (let
+                    ((gerrit-change-singleline-columns '(number branch project subject)))
+                  (gerrit--select-change-from-matching-changes
+                   gerrit-interesting-open-changes-filter))))
+
+  ;; 1) get change metadata
+  ;; 2) determine workspace directory (based on branch and projectname)
+  ;; 3) switch to workspace
+  ;; 4) download change
+  ;; 5) display commit
+  (let* ((change-metadata (car (gerrit-rest-change-query changenr)))
+         (project-name (alist-get 'project change-metadata))
+         (branch (alist-get 'branch change-metadata))
+         (workspace-directory (or (cdr (assoc (cons project-name branch)
+                                              gerrit-project-to-local-workspace-alist))
+                                  ;; TODO completion + write them to file
+                                  (read-directory-name
+                                   (format "Enter directory for project %s" project-name)))))
+    (let ((default-directory workspace-directory))
+      (message "changeinfo: name: %s, branch: %s -> workspace: %s"
+               project-name branch workspace-directory)
+      (gerrit-download changenr) ;; this is async
+      ;; TODO run magit-show-commit
+      ;; only when the above change is downloaded to avoid window-flickering
+      (magit-show-commit "HEAD"))))
+
 (defun gerrit-upload ()
   (interactive)
    (if gerrit-use-gitreview-interface