This is an automated email from the ASF dual-hosted git repository.
mattcasters pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/hop.git
The following commit(s) were added to refs/heads/main by this push:
new d968ec7b33 Add pages for the Git and Git commit perspectives and bring
the git pages up to date with the current Hop Gui. #7120 (#8919)
d968ec7b33 is described below
commit d968ec7b3398e52f26d81bc819343e95353878ad
Author: Adalennis <[email protected]>
AuthorDate: Wed Oct 14 18:43:57 2026 +0200
Add pages for the Git and Git commit perspectives and bring the git pages
up to date with the current Hop Gui. #7120 (#8919)
* Add pages for the Git and Git commit perspectives and bring the git pages
up to date with the current Hop Gui. #7120
* Issue #7120 : Correct the git pages where they do not match the plugin
---------
Co-authored-by: mattcasters <[email protected]>
---
.../hop-gui/hop-gui-file-explorer-right-menu.png | Bin 185129 -> 106517 bytes
.../assets/images/hop-gui/hop-gui-git-toolbar.png | Bin 6195 -> 13835 bytes
.../ROOT/assets/images/hop-gui/hop-gui-no-git.png | Bin 4822 -> 12771 bytes
.../assets/images/icons/git-commit-perspective.svg | 7 ++
.../ROOT/assets/images/icons/git-delete.svg | 24 ++++++
.../ROOT/assets/images/icons/git-perspective.svg | 10 +++
.../ROOT/assets/images/icons/select-target.svg | 4 +
docs/hop-user-manual/modules/ROOT/nav.adoc | 2 +
.../modules/ROOT/pages/hop-gui/hop-gui-git.adoc | 87 +++++++++-----------
.../pages/hop-gui/perspective-file-explorer.adoc | 30 ++++---
.../ROOT/pages/hop-gui/perspective-git-commit.adoc | 76 +++++++++++++++++
.../ROOT/pages/hop-gui/perspective-git.adoc | 90 +++++++++++++++++++++
.../pages/snippets/hop-gui/perspectives-list.adoc | 4 +
13 files changed, 273 insertions(+), 61 deletions(-)
diff --git
a/docs/hop-user-manual/modules/ROOT/assets/images/hop-gui/hop-gui-file-explorer-right-menu.png
b/docs/hop-user-manual/modules/ROOT/assets/images/hop-gui/hop-gui-file-explorer-right-menu.png
index 1c266fd355..17052aea55 100644
Binary files
a/docs/hop-user-manual/modules/ROOT/assets/images/hop-gui/hop-gui-file-explorer-right-menu.png
and
b/docs/hop-user-manual/modules/ROOT/assets/images/hop-gui/hop-gui-file-explorer-right-menu.png
differ
diff --git
a/docs/hop-user-manual/modules/ROOT/assets/images/hop-gui/hop-gui-git-toolbar.png
b/docs/hop-user-manual/modules/ROOT/assets/images/hop-gui/hop-gui-git-toolbar.png
index 60e56daed3..e1a0e35c5a 100644
Binary files
a/docs/hop-user-manual/modules/ROOT/assets/images/hop-gui/hop-gui-git-toolbar.png
and
b/docs/hop-user-manual/modules/ROOT/assets/images/hop-gui/hop-gui-git-toolbar.png
differ
diff --git
a/docs/hop-user-manual/modules/ROOT/assets/images/hop-gui/hop-gui-no-git.png
b/docs/hop-user-manual/modules/ROOT/assets/images/hop-gui/hop-gui-no-git.png
index 2660890c88..870f279333 100644
Binary files
a/docs/hop-user-manual/modules/ROOT/assets/images/hop-gui/hop-gui-no-git.png
and
b/docs/hop-user-manual/modules/ROOT/assets/images/hop-gui/hop-gui-no-git.png
differ
diff --git
a/docs/hop-user-manual/modules/ROOT/assets/images/icons/git-commit-perspective.svg
b/docs/hop-user-manual/modules/ROOT/assets/images/icons/git-commit-perspective.svg
new file mode 100644
index 0000000000..5c17f0836f
--- /dev/null
+++
b/docs/hop-user-manual/modules/ROOT/assets/images/icons/git-commit-perspective.svg
@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg"; width="24px" height="24px" viewBox="0
0 800 800">
+<path fill="#0E3A5A"
d="M700,350H593.75c-27.566-106.962-136.622-171.326-243.584-143.76
+
C279.648,224.414,224.58,279.481,206.406,350H100c-27.614,0-50,22.386-50,50s22.386,50,50,50h106.328
+
c27.481,106.983,136.487,171.433,243.471,143.951C520.441,575.805,575.604,520.642,593.75,450H700c27.613,0,50-22.386,50-50
+ S727.614,350,700,350z
M400,500c-55.229,0-100-44.771-100-100s44.771-100,100-100c55.228,0,100,44.771,100,100
+ C499.94,455.203,455.203,499.939,400,500z"/>
+</svg>
diff --git
a/docs/hop-user-manual/modules/ROOT/assets/images/icons/git-delete.svg
b/docs/hop-user-manual/modules/ROOT/assets/images/icons/git-delete.svg
new file mode 100644
index 0000000000..7e495d3d1f
--- /dev/null
+++ b/docs/hop-user-manual/modules/ROOT/assets/images/icons/git-delete.svg
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+ xmlns="http://www.w3.org/2000/svg";
+ enable-background="new 0 0 97 97"
+ viewBox="0 0 97 97"
+ height="97px"
+ width="97px"
+ y="0px"
+ x="0px"
+ version="1.1">
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage"/>
+ />
+ <g
+ transform="matrix(0.84322823,0,0,0.84322823,0.40051268,0.40098299)"
+ >
+ <path
+ style="fill:#f05133"
+ d="M 92.71,44.408 52.591,4.291 c -2.31,-2.311 -6.057,-2.311
-8.369,0 l -8.33,8.332 10.567,10.567 c 2.456,-0.83 5.272,-0.273 7.229,1.685
1.969,1.97 2.521,4.81 1.67,7.275 l 10.186,10.185 c 2.465,-0.85 5.307,-0.3
7.275,1.671 2.75,2.75 2.75,7.206 0,9.958 -2.752,2.751 -7.208,2.751 -9.961,0
-2.068,-2.07 -2.58,-5.11 -1.531,-7.658 l -9.5,-9.499 v 24.997 c 0.67,0.332
1.303,0.774 1.861,1.332 2.75,2.75 2.75,7.206 0,9.959 -2.75,2.749 -7.209,2.749
-9.957,0 -2.75,-2.754 -2.75,-7.21 0,- [...]
+ </g>
+ <polygon
+ transform="matrix(4.1516888,0,0,4.1516888,-65.646035,-69.674863)"
+ style="fill:#ea102a"
+ points="31.8,39.9 34.7,37 37.6,39.9 38.9,38.5 36,35.6 38.9,32.7
37.6,31.4 34.7,34.3 31.8,31.4 30.4,32.7 33.3,35.6 30.4,38.5 "/>
+</svg>
\ No newline at end of file
diff --git
a/docs/hop-user-manual/modules/ROOT/assets/images/icons/git-perspective.svg
b/docs/hop-user-manual/modules/ROOT/assets/images/icons/git-perspective.svg
new file mode 100644
index 0000000000..1e1ebc1db2
--- /dev/null
+++ b/docs/hop-user-manual/modules/ROOT/assets/images/icons/git-perspective.svg
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<svg xmlns="http://www.w3.org/2000/svg"; width="97px" height="97px" viewBox="0
0 97 97">
+ <path fill="#0e3a5a"
d="M92.71,44.408L52.591,4.291c-2.31-2.311-6.057-2.311-8.369,0l-8.33,8.332L46.459,23.19
+
c2.456-0.83,5.272-0.273,7.229,1.685c1.969,1.97,2.521,4.81,1.67,7.275l10.186,10.185c2.465-0.85,5.307-0.3,7.275,1.671
+
c2.75,2.75,2.75,7.206,0,9.958c-2.752,2.751-7.208,2.751-9.961,0c-2.068-2.07-2.58-5.11-1.531-7.658l-9.5-9.499v24.997
+
c0.67,0.332,1.303,0.774,1.861,1.332c2.75,2.75,2.75,7.206,0,9.959c-2.75,2.749-7.209,2.749-9.957,0c-2.75-2.754-2.75-7.21,0-9.959
+
c0.68-0.679,1.467-1.193,2.307-1.537V36.369c-0.84-0.344-1.625-0.853-2.307-1.537c-2.083-2.082-2.584-5.14-1.516-7.698
+
L31.798,16.715L4.288,44.222c-2.311,2.313-2.311,6.06,0,8.371l40.121,40.118c2.31,2.311,6.056,2.311,8.369,0L92.71,52.779
+ C95.021,50.468,95.021,46.719,92.71,44.408z"/>
+</svg>
diff --git
a/docs/hop-user-manual/modules/ROOT/assets/images/icons/select-target.svg
b/docs/hop-user-manual/modules/ROOT/assets/images/icons/select-target.svg
new file mode 100644
index 0000000000..0cebe61c03
--- /dev/null
+++ b/docs/hop-user-manual/modules/ROOT/assets/images/icons/select-target.svg
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<svg xmlns="http://www.w3.org/2000/svg"; width="1024" height="1024">
+ <path fill="#0E3A5A" d="M850.688 554.666667A341.504 341.504 0 0 1
554.666667 850.688V938.666667h-85.333334v-87.978667A341.504 341.504 0 0 1
173.312 554.666667H85.333333v-85.333334h87.978667A341.504 341.504 0 0 1
469.333333 173.312V85.333333h85.333334v87.978667A341.504 341.504 0 0 1 850.688
469.333333H938.666667v85.333334h-87.978667zM512 768a256 256 0 1 0 0-512 256 256
0 0 0 0 512z m0-128a128 128 0 1 0 0-256 128 128 0 0 0 0 256z" />
+</svg>
\ No newline at end of file
diff --git a/docs/hop-user-manual/modules/ROOT/nav.adoc
b/docs/hop-user-manual/modules/ROOT/nav.adoc
index 7839154912..d50773cee5 100644
--- a/docs/hop-user-manual/modules/ROOT/nav.adoc
+++ b/docs/hop-user-manual/modules/ROOT/nav.adoc
@@ -45,6 +45,8 @@ under the License.
** xref:hop-gui/perspective-ai-advisor.adoc[AI Assistant]
** xref:hop-gui/perspective-database.adoc[Database perspective]
** xref:hop-gui/perspective-search.adoc[Search]
+** xref:hop-gui/perspective-git-commit.adoc[Git commit perspective]
+** xref:hop-gui/perspective-git.adoc[Git perspective]
** xref:hop-gui/hop-gui-git.adoc[Working with git]
** xref:hop-gui/shortcuts.adoc[Keyboard Shortcuts]
** xref:hop-gui/canvas-mouse.adoc[Canvas Mouse Gestures]
diff --git a/docs/hop-user-manual/modules/ROOT/pages/hop-gui/hop-gui-git.adoc
b/docs/hop-user-manual/modules/ROOT/pages/hop-gui/hop-gui-git.adoc
index 82765d2d04..42a8c47704 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/hop-gui/hop-gui-git.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/hop-gui/hop-gui-git.adoc
@@ -15,16 +15,21 @@ specific language governing permissions and limitations
under the License.
////
:imagesdir: ../../assets/images
-:description: Version control is an important aspect of any serious data
orchestration project.. Hop's file explorer perspective offers the basic
functionality to manage your work in git: pull, push, visual diff, commit etc
are all available from a user friendly ui.
+:description: Version control is an important aspect of any serious data
orchestration project. Hop Gui lets you manage your work in git: commit, push,
pull, branches, history and visual diffs.
= Working with git
Version control is an important aspect of any serious data orchestration
project.
-Hop wants to make it as easy as possible to manage versions for your workflows
and pipelines through the integrated git options in the
xref:hop-gui/perspective-file-explorer.adoc[File Explorer perspective].
+Hop wants to make it as easy as possible to manage versions for your workflows
and pipelines.
+When your project folder is a git repository, Hop Gui adds git options in
three places:
+
+* the toolbar, right-click menu and file colors of the
xref:hop-gui/perspective-file-explorer.adoc[File Explorer perspective],
described on this page;
+* the branch menu in the status bar, described on this page;
+* two perspectives of their own: xref:hop-gui/perspective-git-commit.adoc[Git
commit] to review and commit your changes, and
xref:hop-gui/perspective-git.adoc[Git] for branches, tags and the commit
history.
== File Explorer Toolbar
-If you open the file explorer for a project that is not version controlled in
git, the git icons in the file explorer's main toolbar (top left) will be shown
as greyed-out and disabled.
+If you open the file explorer for a project that is not version controlled in
git, the git icons in the file explorer's toolbar will be shown as greyed-out
and disabled.
image::hop-gui/hop-gui-no-git.png[No git available,width="50%"]
@@ -37,7 +42,7 @@ The available options to work with files and the available
git operations in thi
[options="header", cols="1,2,5,1"]
|===
|icon|action|description|shortcut
-|image:icons/arrow-right.svg[width="24px"]|Open selected file|Opens the
selected file in the appropriate editor (pipeline or workflow editor for
workflows and pipelines, text editor for other file.|double-click
+|image:icons/arrow-right.svg[width="24px"]|Open selected file|Opens the
selected file in the appropriate editor (pipeline or workflow editor for
workflows and pipelines, text editor for other files).|F3, double-click
|image:icons/folder-add.svg[width="24px"]|Add folder|adds a new folder at the
selected location. A popup is shown for the folder name.|
|image:getting-started/icons/expand-all.svg[width="24px"]|Expand all
folders|Display all nested folders in the directory tree.|
|image:getting-started/icons/collapse-all.svg[width="24px"]|Collapse all
folders|Hide all nested folders in the directory tree.|
@@ -45,45 +50,55 @@ The available options to work with files and the available
git operations in thi
|image:icons/rename.svg[width="24px"]|Rename the selected file|Makes the
selected file name editable to allow renaming.|F2
|image:icons/refresh.svg[width="24px"]|Refresh|Refreshes the projects folder
and file structure.|F5
|image:getting-started/icons/hide.svg[width="24px"]|Show or hide files|Show or
hide files or directories.|
-|image:icons/git-info.svg[width="24px"]|Git info|Populates the file explorer's
git dialog with version information for the selected file.|
-|image:icons/git-add.svg[width="24px"]|Git Add|Add the selected file to
version control.|
-|image:icons/git-revert.svg[width="24px"]|Git Revert|Revert file to last
committed version (HEAD).|
-|image:icons/git-commit.svg[width="24px"]|Git commit|Commit the latest changes
for the selected file (providing a commit message).|
-|image:icons/push.svg[width="24px"]|Git push|Push the recent changes to the
remote repository.|
-|image:icons/pull.svg[width="24px"]|Git pull|Pull the latest changes from the
remote repository.|
+|image:icons/select-target.svg[width="24px"]|Select opened file|Selects the
file of the active editor tab in the tree.|ALT+F1
+|image:icons/git-info.svg[width="24px"]|Git info|Opens a tab with the git
information of the selected file or folder: status, branch, revisions and
changed files.|
+|image:icons/git-add.svg[width="24px"]|Git Add|Stage the unstaged changes in
the selection, including edits to files git already tracks.|
+|image:icons/git-revert.svg[width="24px"]|Git Revert|Restore modified files in
the selection from the last committed version (HEAD). A new staged file is only
unstaged and stays on disk; deleting it is Git Clean. A dialog lets you pick
the files.|
+|image:icons/git-delete.svg[width="24px"]|Git Clean|Delete files that git does
not track from disk. A dialog lets you pick the files.|
+|image:icons/git-commit.svg[width="24px"]|Git commit|Opens the
xref:hop-gui/perspective-git-commit.adoc[Git commit perspective] to review and
commit your changes. In Hop Web it opens a commit dialog instead.|
|===
-NOTE: Only the available options are availabe at a given time. E.g. `git add`
will not be available for files that already are in version control.
+NOTE: Only the options that apply are available at a given time. Git Add is
available when the selection still has unstaged changes, and it is disabled
once those changes are staged.
+The git options are also available in the right-click menu of the file
explorer tree.
== File Explorer Tree
In the folder and file structure tree below the toolbar, files use a color
coding scheme to indicate the git status of a file:
-* black: unchanged.
-This is the latest version of the file available in git, no changes detected.
+* black: unchanged, or a deleted path.
+An unchanged file is the latest version in git.
+A deletion stays black whether or not it is staged, so it is not red.
* grey: this file is ignored
-* blue: staged for commit.
+* green: a staged add, copy, or rename.
+* blue: a staged content change.
This file is ready to be committed ('Git Commit')
-* red: not staged for commit.
-Add this file to git before changes can be committed ('Git Add').
+* red: an unstaged add, copy, rename, or content change.
+Stage it with 'Git Add' before the changes can be committed.
+
+== Branches in the status bar
+
+The status bar at the bottom of the window shows the current branch next to
the active project and environment.
+Click it to open the branch menu:
+
+* Create branch, Merge branch, Rename branch and Delete branch.
+* Push and Pull.
+* The local and remote-tracking branches. The current local branch is marked;
click another name, including a remote-tracking name, to check that ref out.
== Working with files in git
Add a file::
Click on a file that is not yet staged for commit (red), click 'Git Add'.
-The color of the file changes to blue (staged for commit).
+The color of the file changes to green (staged add, copy, or rename) or blue
(staged content change).
Commit a file::
-Click on a file that is staged for commit (blue), click 'Git Commit'.
-A popup dialog will ask to confirm the file to commit, and will show a popup
for your commit message.
-Change the default 'Commit Message' to a commit message that describes the
changes you made to the file.
+Click 'Git Commit' to open the xref:hop-gui/perspective-git-commit.adoc[Git
commit perspective], check the files to commit, enter a commit message and
click 'Commit'.
The file color changes to black (no changes).
Show git info::
Click on a file that is under version control (black or blue).
The file explorer will show the git status for this file: the file or folder,
status, branch and a revisions table (list of previous commits).
-Select one of the available commits to show the changed files to show the
changed files for that revision.
+Select one of the available commits to show the changed files for that
revision.
Select any of the files in the revision from the 'Changed files' list to show
the git diff information on the right hand side.
For workflows and pipelines, click 'Visual diff' to open the before and after
versions of the file in new tabs.
Hop will show an additional icon in the upper right corner of the action or
transform icon to indicate the git change that was made (green for added or
yellow for changed)
@@ -95,35 +110,7 @@ Uncheck "Ignore position in the visual diff" in the
configuration options below
A transform or action that was renamed is marked as changed, rather than as
one that was removed and another that was added.
The hops around it are left alone.
-This is recognised as long as the rename is all that happened to it, a move
aside: renaming and editing in the same commit still shows up as a removal plus
an addition, because there is nothing left to recognise it by.
-
-== Git Commit Perspective
-
-The git commit perspective (`CTRL+SHIFT+O`, `CMD+SHIFT+O` on macOS) lists your
changes in the same three groups `git status` reports:
-
-Staged:: added to git's index with 'Add', part of the next commit.
-Unstaged:: changed files that git tracks, but the changes are not in the index.
-Untracked:: files git doesn't know about yet, because they were never added.
-
-The toolbar and right-click options act on the files whose checkbox is ticked,
not on the highlighted row.
-Staged and unstaged files are ticked for you, so a commit takes your work in
progress along: untick a file (or unstage it) to leave it out.
-Untracked files are listed but never ticked: committing a file for the first
time is something you decide, tick it yourself to include it.
-
-[options="header", cols="1,2,5,1"]
-|===
-|icon|action|description|shortcut
-|image:icons/refresh.svg[width="24px"]|Refresh|Reload the list of staged and
unstaged files.|F5
-|image:icons/git-add.svg[width="24px"]|Add|Stage the checked unstaged or
untracked files. They move to 'Staged' and become part of the next commit. For
an untracked file this is also what puts it under version control.|CTRL+ALT+A
-|image:icons/git-unstage.svg[width="24px"]|Unstage|Take the checked files out
of the next commit. They move back to 'Unstaged' (or to 'Untracked' if they
were never committed before), your changes are kept.|CTRL+ALT+U
-|image:icons/git-restore.svg[width="24px"]|Restore|Throw the changes in the
checked files away and restore the last committed version (HEAD). Asks for
confirmation.|CTRL+ALT+Z
-|image:icons/delete.svg[width="24px"]|Delete|Delete the checked files from
disk.|DEL
-|===
-
-WARNING: Unstage and Restore both act on staged files, but they do very
different things.
-Unstage only takes a file out of the next commit and keeps your work, Restore
throws your changes away.
-That is why Restore asks for confirmation and Unstage does not: nothing is
lost by unstaging, you can stage the file again with 'Add'.
-
-The same options are available in the right-click menu of the file list.
+This is recognised as long as the rename is all that happened to it, apart
from a move: renaming and editing in the same commit still shows up as a
removal plus an addition, because there is nothing left to recognise it by.
== Git Configuration options
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/hop-gui/perspective-file-explorer.adoc
b/docs/hop-user-manual/modules/ROOT/pages/hop-gui/perspective-file-explorer.adoc
index dc9f5ac2a9..32c1eb4518 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/hop-gui/perspective-file-explorer.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/hop-gui/perspective-file-explorer.adoc
@@ -65,6 +65,7 @@ image::hop-gui/perspective-explorer-toolbar-items.png[File
explorer toolbar item
* Rename: Rename a file or folder. Only one file or folder at a time.
* Refresh: Refresh the file list.
* Show or hide files: Show or hide files or directories.
+* Select opened file (`ALT+F1`): Select the file of the active editor tab in
the tree.
New pipelines, workflows and files are created from the file explorer's
right-click menu rather than the toolbar; see the "Right-click menu options"
section below.
@@ -92,17 +93,21 @@
image::hop-gui/configuration-perspective-open-help-pages-in.png[Open help pages
=== Description
-If the git plugin (folder `plugins/misc/git`) is installed, the file explorer
will look for a `.git/config` file in the project home folder. It this exists
the explorer perspective will start to color code the files listed:
+If the git plugin (folder `plugins/misc/git`) is installed, the file explorer
will look for a `.git/config` file in the project home folder. If this exists
the explorer perspective will start to color code the files listed:
-* red: the file has not been added to git (un-staged).
-* blue: the file has been changed (staged).
+* red: an unstaged add, copy, rename, or content change.
+* green: a staged add, copy, or rename.
+* blue: a staged content change.
+* black: a deleted path, staged or not.
* gray: the file is ignored by git.
+See xref:hop-gui/hop-gui-git.adoc[Working with git] for all the git options in
Hop Gui.
+
=== Git
==== Git info
-The "Git Info" icon in the toolbar will be enabled if there is information
regarding the file or folder that is selected. If you click on it, you'll be
able to all sorts of information regarding the git history in a new tab:
+The "Git Info" icon in the toolbar will be enabled if there is information
regarding the file or folder that is selected. If you click on it, you'll be
able to see all sorts of information regarding the git history in a new tab:
image::hop-gui/perspective-explorer-git-info-panel.png[Git information shown
in a tab]
@@ -110,7 +115,7 @@ Below the revision history you can see the revisions of a
file. If you select a
image::hop-gui/perspective-explorer-git-visual-diff-example.png[Git visual
diff example]
-Small information icons will be added to the various transforms, actions and
hops to indicate if they were changes, deleted or added.
+Small information icons will be added to the various transforms, actions and
hops to indicate if they were changed, deleted or added.
=== Right-click menu options
The right-click menu in Apache Hop Git integration offers several useful
options to help manage your files and Git operations directly from the
interface. Here’s a breakdown of each option:
@@ -127,8 +132,9 @@ The right-click menu in Apache Hop Git integration offers
several useful options
* Copy path: Copies the full path of the selected file or folder to your
clipboard, useful for quick navigation or sharing the location with others.
* Git Info: Displays detailed information about the Git status of the selected
file, including any recent changes.
* Git Add: Stages the selected file(s) for commit, meaning the changes are
prepared for inclusion in your next Git commit.
-* Git Revert: Reverts any changes made to the selected file, restoring it to
the last committed state. This is helpful when you need to undo accidental
modifications.
-* Git Commit: Opens a dialog for committing staged changes to your local Git
repository. You can add a descriptive commit message summarizing your updates.
+* Git Revert: Restores modified files in the selection from the last committed
version (HEAD). A new staged file is only unstaged and stays on disk; deleting
it is Git Clean. A dialog lets you pick the files.
+* Git Clean: Deletes files that git does not track from disk, after you pick
them in a dialog.
+* Git Commit: Opens the xref:hop-gui/perspective-git-commit.adoc[Git commit
perspective], where you review your changes and commit them with a message. In
Hop Web it opens a commit dialog instead.
* Delete: Removes the selected file or folder from your project. Make sure to
use this carefully, as it permanently deletes the item from your directory.
image::hop-gui/hop-gui-file-explorer-right-menu.png[git right-click menu
options in the explorer perspective]
@@ -137,11 +143,13 @@ image::hop-gui/hop-gui-file-explorer-right-menu.png[git
right-click menu options
Here are the basic git operations that are supported:
+* Git Info: show the git status and history of the file or folder.
* Git Add: stage the file to include it in a commit.
-* Git Commit: commit changes to origin.
-* Git Revert: checkout file or folder to revert changes.
-* Git Push: push changes.
-* Git Pull: pull changes.
+* Git Revert: restore modified files from HEAD. A new staged file is only
unstaged and stays on disk.
+* Git Clean: delete files git does not track.
+* Git Commit: open the Git commit perspective to commit your changes. In Hop
Web it opens a commit dialog instead.
+
+Push, pull and the branch operations are in the branch menu of the status bar
and in the xref:hop-gui/perspective-git.adoc[Git perspective].
You can access these operations from the toolbar above the file explorer tree:
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/hop-gui/perspective-git-commit.adoc
b/docs/hop-user-manual/modules/ROOT/pages/hop-gui/perspective-git-commit.adoc
new file mode 100644
index 0000000000..da6cdd76b1
--- /dev/null
+++
b/docs/hop-user-manual/modules/ROOT/pages/hop-gui/perspective-git-commit.adoc
@@ -0,0 +1,76 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+////
+:imagesdir: ../../assets/images
+:description: The Git commit perspective lists your staged, unstaged and
untracked changes so you can review them and commit them, with or without a
push.
+
+= Git Commit Perspective
+
+Icon: image:icons/git-commit-perspective.svg[width="24px"]
+
+Keyboard shortcut: `CTRL+SHIFT+O` (`CMD+SHIFT+O` on macOS)
+
+== Description
+
+The Git commit perspective is where you review the changes in your project and
commit them.
+It is available when the project folder is a git repository.
+See xref:hop-gui/hop-gui-git.adoc[Working with git] for the other git options
in Hop Gui.
+
+== The list of changes
+
+The perspective lists your changes in the same three groups `git status`
reports:
+
+Staged:: added to git's index with 'Add', part of the next commit.
+Unstaged:: changed files that git tracks, but the changes are not in the index.
+Untracked:: files git doesn't know about yet, because they were never added.
+
+Add, Unstage, Restore, Delete and Add to .gitignore act on the files whose
checkbox is ticked, not on the highlighted row.
+Show text diff and Show visual diff follow the first highlighted file instead.
+Staged and unstaged files are ticked for you, so a commit takes your work in
progress along: untick a file (or unstage it) to leave it out.
+Untracked files are listed but never ticked: committing a file for the first
time is something you decide, tick it yourself to include it.
+
+[options="header", cols="1,2,5,1"]
+|===
+|icon|action|description|shortcut
+|image:icons/refresh.svg[width="24px"]|Refresh|Reload the list of staged and
unstaged files.|F5
+|image:icons/git-add.svg[width="24px"]|Add|Stage the checked unstaged or
untracked files. They move to 'Staged' and become part of the next commit. For
an untracked file this is also what puts it under version control.|CTRL+ALT+A
+|image:icons/git-unstage.svg[width="24px"]|Unstage|Take the checked files out
of the next commit. They move back to 'Unstaged' (or to 'Untracked' if they
were never committed before), your changes are kept.|CTRL+ALT+U
+|image:icons/git-restore.svg[width="24px"]|Restore|Discard staged edits to
files git already tracks and restore the last committed version (HEAD). A
staged new file is only unstaged and stays on disk, unless 'Delete local copies
of added files' is checked. That toggle is off by default. Asks for
confirmation.|CTRL+ALT+Z
+|image:icons/delete.svg[width="24px"]|Delete|Delete the checked files from
disk.|DEL
+|===
+
+WARNING: Unstage and Restore both act on staged files, but they do very
different things.
+Unstage only takes a file out of the next commit and keeps your work.
+Restore discards staged edits to files git already tracks.
+A staged new file is only unstaged unless you check 'Delete local copies of
added files'.
+That is why Restore asks for confirmation and Unstage does not: nothing is
lost by unstaging, you can stage the file again with 'Add'.
+
+The same options are available in the right-click menu of the file list,
together with:
+
+* Add to .gitignore: have git ignore the file from now on.
+* Show text diff (`CTRL+D`): the changes in the first highlighted file as
text. This follows the highlight, not the checkbox.
+* Show visual diff (`CTRL+SHIFT+D`): for a pipeline or workflow, open the
before and after versions of the first highlighted file side by side. This
follows the highlight, not the checkbox.
+
+== Committing
+
+Enter a commit message below the list of changes, then click:
+
+Commit:: commit the checked files.
+Commit and Push:: commit the checked files and push the commit to the remote.
+
+Tick 'Amend' first to put the checked files into your last commit instead of
creating a new one.
+
+`CTRL+K` (`CMD+K` on macOS) ticks all staged and unstaged files and moves the
cursor to the commit message, so committing all your work in progress is
`CTRL+K`, typing the message and 'Commit'.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/hop-gui/perspective-git.adoc
b/docs/hop-user-manual/modules/ROOT/pages/hop-gui/perspective-git.adoc
new file mode 100644
index 0000000000..00ccb05cdf
--- /dev/null
+++ b/docs/hop-user-manual/modules/ROOT/pages/hop-gui/perspective-git.adoc
@@ -0,0 +1,90 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+////
+:imagesdir: ../../assets/images
+:description: The Git perspective shows the branches, tags and commit history
of your project, and lets you check out, merge, tag, revert and cherry-pick
from there.
+
+= Git Perspective
+
+Icon: image:icons/git-perspective.svg[width="24px"]
+
+Keyboard shortcut: `CTRL+SHIFT+G` (`CMD+SHIFT+G` on macOS)
+
+== Description
+
+The Git perspective shows the branches, tags and commit history of your
project.
+It is available when the project folder is a git repository.
+To commit your changes, use the xref:hop-gui/perspective-git-commit.adoc[Git
commit perspective].
+See xref:hop-gui/hop-gui-git.adoc[Working with git] for the other git options
in Hop Gui.
+
+The perspective has four parts:
+
+. On the left, the branches and tags: Local, Remote and Tags.
+A search field above Local, Remote and Tags filters the commit list by
message, author and abbreviated id.
+. In the middle, the commit history: a graph of the branches, with their names
next to the commits they point to, and the message, author, date and id of each
commit.
+When you have uncommitted changes, they are shown as the first line.
+. On the right, the files changed in the selected commit.
+. Below them, the differences in the selected file.
+
+== Branches and tags
+
+Right-click a branch or tag on the left:
+
+[options="header", cols="2,5,1"]
+|===
+|action|description|shortcut
+|Checkout|Check out the branch or tag.|
+|Create branch from|Create a new branch that starts at this branch or tag.|
+|Merge into|Merge this branch into the current branch.|
+|Fetch|Fetch from the remote. Available on any branch or tag.|
+|Pull|Pull the current branch from the remote. Offered only when a local
branch is selected.|
+|Push|Push the selected local branch or tag. Not available on a
remote-tracking branch.|
+|Rename|Rename a local branch, or a remote-tracking branch other than the
remote's default branch. Not available on a tag.|F2
+|Delete|Delete the branch or tag.|DEL
+|===
+
+== The commit history
+
+The toolbar above the history refreshes it, creates a branch or tag at the
selected commit, cherry-picks the selected commit, and fetches, pulls
(`CTRL+T`) and pushes.
+Its eye button shows or hides commits that are only reachable from other local
branches.
+
+Right-click a commit for more:
+
+[options="header", cols="2,5"]
+|===
+|action|description
+|Create branch, Create tag|Create a branch or a tag at this commit.
+|Checkout Revision|Check out this commit.
+|Copy Revision Id|Copy the id of the commit to the clipboard.
+|Reset current branch to here|Move the current branch to this commit. You
choose what happens to the changes made after it: keep them staged (soft), keep
them unstaged (mixed) or discard them (hard).
+|Revert commit|Create a new commit that undoes this one.
+|Cherry-pick commit|Apply this commit to the current branch.
+|===
+
+== The files of a commit
+
+Select a file in the changed files to see its differences below.
+The toolbar above the files and their right-click menu act on the selected
file:
+
+[options="header", cols="2,5,1"]
+|===
+|action|description|shortcut
+|Show text diff|Show the changes in the file as text.|CTRL+D
+|Show visual diff|For a pipeline or workflow, open the versions before and
after the commit side by side.|CTRL+SHIFT+D
+|Copy Path|Copy the path of the file to the clipboard.|
+|Revert file|Undo what this commit did to the file, and commit that.|
+|Cherry-pick file|Take the version of the file in this commit, and commit it.|
+|===
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/snippets/hop-gui/perspectives-list.adoc
b/docs/hop-user-manual/modules/ROOT/pages/snippets/hop-gui/perspectives-list.adoc
index 50dc3ba619..09a9e9bd9b 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/snippets/hop-gui/perspectives-list.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/snippets/hop-gui/perspectives-list.adoc
@@ -26,6 +26,10 @@ under the License.
* image:icons/ai-provider.svg[width="24px"]
xref:hop-gui/perspective-ai-advisor.adoc[AI Assistant] (also as a floating
window or bottom-dock tab; off by default)
+* image:icons/git-commit-perspective.svg[width="24px"]
xref:hop-gui/perspective-git-commit.adoc[Git commit] (when the project is a git
repository)
+
+* image:icons/git-perspective.svg[width="24px"]
xref:hop-gui/perspective-git.adoc[Git] (when the project is a git repository)
+
* image:icons/plugin.svg[width="24px"]
xref:hop-gui/perspective-plugin.adoc[Plugins explorer]
* image:icons/graph_logging.svg[width="24px"]
xref:hop-gui/perspective-graph-logging.adoc[Graph logging]
