Merge pull request #167 from boutproject/better-git-diff-fail

Recommend editable installs for developers

doc/developer/developer.rst

@@ -1,6 +1,18 @@
 Developing hypnotoad
 ====================
 
+When installing from the source code git repo for development, it is
+recommended to do an editable install ::
+
+    $ pip install --user -e .
+
+This method means the installed modules and command line tools link to the
+source code, so reflect changes you make, and avoids a possible error if the
+repo has uncommitted changes (is 'dirty') where ``git diff`` fails to run on
+the installed code. Note, if you use ``conda`` make sure all the dependencies
+(see ``pyproject.toml``) are already installed to avoid them being
+``pip``-installed and messing up dependency tracking.
+
 .. toctree::
 
    equilibrium

doc/whats-new.md

@@ -4,6 +4,12 @@ Release history
 0.5.1 (18th January 2023)
 -------------------------
 
+### Bug fixes
+
+- Document that editable installs are recommended for developers in manual and
+  exception message (#167)\
+  By [John Omotani](https://github.com/johnomotani)
+
 ### New features
 
 - `PsiContour.plot()` and `FineContour.plot()` can be called with an `ax`

hypnotoad/core/mesh.py

@@ -2573,9 +2573,18 @@ def __init__(self, equilibrium, settings):
 
             hypnotoad_path = Path(hypnotoad_init_file).parent
 
-            retval, self.git_diff = shell_safe(
-                "cd " + str(hypnotoad_path) + "&& git diff", pipe=True
-            )
+            try:
+                retval, self.git_diff = shell_safe(
+                    "cd " + str(hypnotoad_path) + "&& git diff", pipe=True
+                )
+            except RuntimeError as e:
+                raise RuntimeError(
+                    "`git diff` failed. It is recommended to do an editable install "
+                    "using `pip --user -e .` when developing. If you did a "
+                    "non-editable install, this error can occur if the repo was "
+                    "'dirty' when installed.\n\nThe error message was:\n" + str(e)
+                )
+
             self.git_diff = self.git_diff.strip()
 
         # Generate MeshRegion object for each section of the mesh