1. General purpose

Agite (Ada GIT Editor) is a graphical front end of the Git configuration management tool. It proposes a view directory-oriented of the files and history.

The major functions are the navigation in directories, history, file status, graphical diff, commit, push, pull, merge and rebase branch, tags and stash.

2. Command line

Usage: agite [ -n | --no-history ] [ <path> | -p | --previous ]

By default Agite continuously stores the current directory in its configuration file. This allows restarting Agite in the same directory as when it was stopped, by providing the argument -p or --previous at start-up.

On the other hand this feature is not compatible with several instances of Agite running in parallel. Only one instance of the program shall save the current directory, which is achieved by providing the argument -n or --no-history to all the other instances.

Instead of the previous directory, the start-up directory can be explicitly specified in the command line with <path>. If no path nor --previous is specified, then by default Agite starts in the current directory.

3. Environment variables

AFPX_DATA_DIR

Agite is based on Afpx screen manager, which reads the configuration files AFPX.DSC, AFPX.FLD and AFPX.INI. Either theses files are in the current directory from which Agite is launched, or the environment variable AFPX_DATA_DIR must be set to the directory containing these files.

Note
Agite unsets AFPX_DATA_DIR at start-up, so its children don’t inherit from this setting.
AGITE_CONF_FILE

Agite allows several settings to be defined in a configuration file. By default this file is ${HOME}/.agite/agite.xml but this can be overridden by setting the environment variable AGITE_CONF_FILE to the full path and name of the configuration file.

Note
At least the variable HOME or AGITE_CONF_FILE must be set in the environment, otherwise Agite doesn’t start.
GIT_DIR

Agite needs to know the root directory of the current Git repository (if any). It finds it by locating, in the current directory or above, the Git technical directory. By default it is named .git but this can be overridden by setting the environment variable GIT_DIR to the name (without path) of the Git directory.

GIT_EDITOR

Agite sets this variable to the value configured as editor.

4. Configuration file

4.1. User defined configuration

At start-up Agite reads some user-defined parameters from its configuration file:

xterm

This defines the command to be launched when the XTerm button is selected. Example: gnome-terminal --zoom=0.9.
The default name for this button is "Xterm", but you can set the Name attribute of the XML element in order to specifiy another name for the button (8 characters max).

editor

This defines the command to be launched for editing a file (for example with the Edit button). A space and the file name will be concatenated to this string.

Note
This command shall start a GUI editor like gedit or a xterm -e vi.
The editor should not return until completion, so that Agite detects when the editor exits and can properly refresh the status of files.
viewer

This defines the command to be launched for viewing a file (for example with the View button). As the editor it must be a GUI, for example xterm -e cat or xterm -e vi -M.

differator

This defines the command to be launched for performing a Diff between two versions of a file. Agite will launch git difftool -y -x <differator> HEAD -- <file> for the diff between current file and the Git repository and git difftool -y -x <differator> <ref_rev> <comp_rev> -- <file> for the diff between two revisions of a file.

make

This defines the command to be launched for the local compilation with the Make button. It shall launch a GUI. Example: xterm -e 'sh -c "make; echo -n Done.; read a"'
The default name for this button is "Make" and, as for the xterm button, you can set the Name attribute of the XML element in order to specify another name for the button (8 characters max).

period

Agite refreshes the current status of files in the directory menu when it starts the editor and when the editor exits. This is because the edition can modify the current status of local files. Still, it is also possible that a stand-alone program modifes the status of local files. This is why Agite periodically checks and redisplays the status of local files in the directory and in the commit menus. This parameter defines the period in seconds of this automatic check.

Setting the value to 0.0 disables the feature.

Note
Agite refreshes the screen when the mouse cursor enters its window.
A manual refresh is always possible with the Reread button.

list_tags

By default, when starting the tags menu and if no template is specified, Agite does not list all the tags and lets you enter a template. This prevents spending to much time in the reading of all the tags of the repository.

Setting the value to true instructs Agite to list all the tags by default when entering this menu.

history

When reading the history of a directory or file, Agite only scans and displays the amount of entries specified in this parameter (a button, All, allows listing all the entries).

Setting the value to 0 disables the feature and Agite will always list all the entries of the history.

4.2. Agite persistent data

Agite also uses the configuration file to store information from one invocation to another.

last_dir

Agite stores the current directory (each time it changes) in this entry. See the argument -p (--previous) for how to use this feature and the argument -n (--no-history) for how to disable this feature.

bookmarks

Agite stores the bookmarks (each time you change them) in this section:

  • blank lines have no Name nor content,

  • separators have a Name and no content,

  • bookmarks have a content and possibly a Name.

comment

Agite saves the text of the current comment of the commit, so that it is retrieved from one session to another.

Note
The DTD file agite.dtd must be located according to the 'DOCTYPE' directive of the Agite XML configuration file.
You may modify these persistent values, providing that:
* Agite is not running (it would overwrite your changes),
* You don’t add XML comments (Agite would remove them),
* The file agite.xlm complies with the DTD agite.dtd.
Note
In case of problem (crash), a backup of the configuration file may be found at the same location and name as the configuration file, with the suffix ".tmp".

5. Ergonomy

Agite implements a succession of menus in a series of screens. All the screens have the same fixed size.

In each screen you can use the keyboard, the three buttons and the wheel of the mouse in order to interact with agite lists, get fields and buttons.

5.1. List

Selecting item(s) in the list
  • The left mouse button is used to define the main selection. The selected item becomes green. Any new main selection replaces the previous.

  • On most lists, a double click with the left mouse button triggers a pre-defined action on the selected item.

  • The right mouse button is used on some lists (branches, history and cherry-pick) to make a second selection. The selected item becomes black.
    Any main selection on the second selection makes it becomming the main selection. Any second re-selection of the second selection itself un-selects it. Any new second selection replaces the previous.

    This dual selection is used either to compare some items, to apply an action to a range of items, or to add a second criteria to an action.

Clicking on an item and releasing on another has no effect.

Scrolling the list
  • Scrolling by one line up/down can be done by either:

    • up and down arrow keys

    • mouse wheel

    • Up and Down buttons

  • Scrolling by one page up/down can be done by either:

    • shift + up and down arrow keys

    • page-up and page-down keys

    • shift + mouse wheel

    • PgUp and PgDown buttons

  • Scrolling by ten pages up/down can be done by either:

    • control + up and down arrow keys

    • shift + page-up and page-down keys

    • control + mouse wheel

  • Moving to top/bottom can be done by either:

    • control + page-up and page-down keys

    • Top and Bottom buttons

  • Scroll bar
    Besides the history list (which can be long) is a scroll-bar that indicates the relative position of the items currently displayed in the list window, versus the whole list. Clicking and releasing in this scroll-bar scrolls the list so that it matches the release position.

  • Quick search
    On top of the directory list are special buttons that allow searching an entry of the list by its first letter. The item becomes selected and the list is scrolled to move the item on top of the list window.

5.2. Get fields

Get fields are identified by their background in white.
Each get field is on one row only.

  • Selection
    When several get fields are defined in a screen, it is possible to select a get field by clicking in it.
    Alternatively the keyboard keys Tab and Shift-Tab allow changing to the next or to the previous get field.
    Finally, contiguous get fields (like the comment of a commit) allow continuous input: when the cursor reaches the end of a field it moves to the next field, and vice versa.

  • Edition
    In a get field, the following actions are possible with the keyboard keys.
    Note that some get fields (target directory, commit comment and bookmark edition) can scroll horizontally to allow a string wider than the get area.

    • Clicking somewhere in the field with the mouse left button moves the cursor at this position or after the last significant character

    • Clicking with the mouse middle button pastes the current X11 selection buffer at the beginning of the field.
      Note: This X11 selection buffer is different from the clipboard of the window manager (accessed in some applications by Ctrl-C, Ctrl-V and with the right mouse button opening a pop-up menu), which is not available in Agite, neither for copy nor for paste.

    • Home and End: move to the boundaries of the get area

    • Left/right arrows: navigate in the string

    • A character input, Backspace and Suppr edit the string

    • Shift+Suppr clears the string from the current position to the end

    • Ctrl+Suppr clears the whole string (and moves to the beginning of it)

    • Insert: toggles the insert/replace mode (in Insert mode the cursor becomes a '^')

    • Ctrl+Right/Left arrow: move to the first/last significant character of the string

    • Shift+Right/Left arrow: move to the first/last character of the string.

5.3. Buttons

Several buttons are defined in each screen. They can be active or not depending on the validity of the corresponding action on the current target (e.g. selection in the list). Clicking and releasing on one button triggers an action that can:

  • apply to the list selection,

  • scroll the list,

  • use or change the content of get fields

  • launch a Got command…

5.4. Whole screen

Keys

Only the following keyboard keys can trigger an action with a wider scope than the input of strings:

  • Return: usually makes a predefined action for the screen, like validating the content of the get fields, or launching an action on the list selection.

  • Escape: cancels the current action or returns to the previous screen.

  • Ctrl-C: requests agite to exit (same as the 'X' button in the title of the X window of Agite, or as clicking in the Exit button of the directory menu).

6. Agite screens

Agite is based on the following main menus:

  • Directory: This is the 'root' menu and the initial menu at start-up. It shows the content of the current directory.

  • Branches: This menu allows managing local and remote tracking branches.

  • Bookmarks: This menu allows bookmarking directories and quickly jumping to a bookmark.

  • History: This shows the Git history of a file or directory, the list of commits that have modified the file(s).

  • Tag: This allows tagging a commit.

  • Detail: This shows information on a commit or a tag, including the list of files modified by the commit.

  • Checkout: This allows checking out a commit or a tag.

  • Tags: This lists the tags and allows managing them.

  • CherryPick: This menu allows performing a cherry-pick of commits from a local branch.

  • Commit: This shows all the local modifications of the repository and allows staging and commiting them.

  • Push: This allows pushing a branch or tag into a remote repository.

  • Stash: This allows stashing the local repository and managing the list of stashes.

  • Pull: This allows pulling, fetching or checking out a branch from a remote repository.

  • Reset: This allows cleaning or doing a hard/mixed/soft reset of the current repository.

The navigation between the screens is as follows:

                                +-----------+
                            /-->| Bookmarks |
                           /    +-----------+
                          /     +----------+          +------------+
                         /----->| Branches |--+------>| CherryPick |--+
                        /       +---+------+ /        +------------+  |
                       /            |       /                         |
                      /             |      /          +-----+         |
                     /              |     /---------->| Tag |         |
                    /               V    /            +-----+         |
                   /            +-------+-+           +--------+      |
                  /------------>| History |<-+-----+->| Detail |<-----+
                 /              +-------+-+   \   /   +--------+      |
                /               +------+ \     \ /    +----------+    |
               /----------------| Tags |--+-----+---->| Checkout |    |
              /                 +------+   \          +----------+    |
+---------- +/                  +-------+   \         +------+        |
| Directory |------------------>| Commit|----+------->| Push |        |
+---------- +\                  +---+---+<-\          +------+        |
              \                     |       \                         |
               \                    V        \                        |
                \               +-------+     \-----------------------+
                 \------------->| Stash |
                  \             +-------+
                   \            +------+
                    \---------->| Pull |
                                +------+
                   +-------+
                   | Reset |
                   +-------+

There are also a confirmation screen and an error screen that are called when necessary.

Note
The history and tags menus call the detail and checkout menus.
The tags and commit menus call the push menu.
The tags menu calls the history menu without allowing modifications, and the detail menu without allowing modifications nor tagging.
The branches menu calls the history menu without allowing modifications nor tagging.
The cherry-pick menu calls the detail menu, but without allowing modifications.
The cherry-pick menu calls the commit menu in a specific mode where is does not allow to call the push menu.
The reset menu is called by the directory, the history, the branch and the commit menus.
Note
All the screen transitions are based on the call-return scheme.
So please note the double arrow between history and detail: from the history of a file (or dir) you can select a commit and see its detail. In this new screen you can select a file and see its history, and so on… Once this is done you need to "un-stack" all these menus (by clicking on the Back button of each) in order to go back to the directory menu.
Also please note that sometimes a successuful action in a menu leads to automatically go back to the ancestor of this menu, sometimes directly back to the directory menu.

6.1. Directory

The directory menu lists the content, subdirectories and files, of the current directory. Starting from top, the areas and fields are:

Environment
Title

The first line shows in the middle the name and current version of Agite.

Branch

On the left is the indication of the current Git branch. Clicking on the branch name launches the branches menu.

Host

On the right is the indication of current host (which normally is also indicated in the title of the X window of Agite).

Directories
Root

This line shows the root directory of the current Git repository. Clicking in this field changes the current directory to the root.

Go

This line shows the current directory. This field can be modified by:

  • changing / entering a new path with the keyboard (you can use Ctrl + Suppr to clear the field),

  • clicking on Reread to restore it to the current directory,

  • clicking on PopD to restore it to a path previously pushed.

Then it is possible to change to the new path by hitting the key Return or by clicking on the Go button.
This text field can scroll horizontally to accomodate to long paths.
After clicking on the Go button (but not after hitting Return) the new path is copied into the X11 selection buffer (for a paste with the middle mouse button, see X11 selection).

Reread

Normally Agite re-scans the current directory and refreshes the list and status when necessary, and also periodically if the feature is enabled (see period configuration option). This button explicitly refreshes the current list and status of files and also resets the Go field to the current directory.

Dir Up

This button allows moving up to parent directory.

Bookmarks

This button launches the bookmarks menu.

PushD and PopD

The PushD button allows storing the current directory, and later on the PopD button allows moving back to it.

  • How it works: Agite keeps a cache of two paths, D1 and D2. PushD saves D1 as D2 and pushes the current directory as D1. PopD swaps D1 and D2 (if D2 is not empty) and copies the new D1 into the Go field.

  • How to use it: At start-up, the current the directory is automatically pushed. As soon as you move to another directory, clicking on PopD then on Go allows moving back to the original one. Once two directories have been pushed, clicking on PopD then on Go allows swapping between both directories (so, in fact, PopD does not pop).

  • Warning: Keep in mind that only the first directory (where Agite starts) is automatically pushed. Changing to a new directory doesn’t make it automatically pushed. Popping doesn’t lead to push the current directory either. For example, if you PushD the directory A, then change to B (and do not explicitly push it), then change to C, then PopD, then Agite will change to directory A (not B).

  • Warning: Keep in mind that PopD swaps D1 and D2 before copying D1 into Go. For example, if you start in directory A, then change to B, then push it, then change to C, then PopD, Agite will copy the path of directory A (not B). A second PopD, will copy the path of B.

List
Symbolic links

On top of the list is a Sym checkbox that toggles showing in the list the target of symbolic links.

Quick search

On top of the list is a quick search area on two rows. Clicking in any character of this area triggers a search of the first file starting with this character. If found, the file becomes selected in the list and at the top of the list area. Otherwise the selection is unchanged.
A tick box button allows searching for the directory D (starting with the character that will be clicked) instead of a file F. You need to tick the box first, then click on a character.

The list itself

The list shows the directories then the files of the current directory, in alphabetical order.
The criteria of .gitignore are used for listing the files, but not the directories. The ignored directory are listed anyway, with their files being ignored but not their subdirectories.

Each directory starts with three spaces then the name then a '/'.

Each file is preceded by two characters of its Git index and local status (see man git-status) then a space, then the name. Git status can be:

  • ' ' = unmodified

  • ? = unknown

  • M = modified

  • T = type modified

  • A = added

  • D = deleted

  • R = renamed

  • C = copied

  • U = updated but unmerged

After the name, a character represents the kind of entry:

  • ' ' fo a file,

  • @ for a symbolic link,

  • / for a directory,

  • ? for other or unknown kind (of a deleted entry).

If the entry is a symbolic link and if the resolution of the symlink targets is enabled, then the kind is followed by " → " (" ⇒ " if the link is broken) then the local name or full path of the final target (after recusrsive resolution).

Only one entry is selected at a time (in green).

A single click selects an entry for edition, difference from the Git reference, history, add or revert operation.

A double click on a directory changes the current directory to it.
A double click on a file launches the edition on it.
A double click on a symbolic link makes one or the other (or nothing), depending on the target of the link.

Navigation in the list

The simplest way to navigate in the list is to use the wheel of the mouse. Combine it with Shift for scrolling by one page and with Ctrl for scrolling by ten pages.

Another way is to use the navigation buttons Top, PgUp, Up, Down, PgDown and Bottom. The Center button scrolls the list so that the selected entry is as most as possible in the middle of the list area.

Another way is to use the keyboard: Up and Down arrows, Page Up, Page Down, Ctrl + Page Up (for Top) and Ctrl + Page Down (for Bottom).

All the lists of Agite screens have the same means for navigation.

Note
Keep in mind that the quick search is also a good way to quickly find a file or directory.
Actions on the current selection in the list

Edit

This button launches the editor (defined in the editor entry of the configuration file) on the file currently selected in the list, as a double click on this file would do.
It is not active if the current entry is a directory.

Diff

On a file, this button launches the graphical difference tool (defined in the differator entry of the configuration file) to show the current modifications (if any) of the selected file. It shows the differences between the currently modified file and the version at the head of current branch.
On a un-modified file it shows the last update of the file (the difference introduced by the last commit involving the file).

On a directory (including ./ but excluding ../), this button asks for confirmation then launches the difference on all the modified files of the selected directory and of its sub-directories.
It is not active if the selected directory is the parent directory entry (../) or if the selected file has the status unknown. It has no effect if there is no modified file under the selected directory.

Hist

This button activates the history menu that shows the history of the current file or directory.

Add

Adds to Git the current directory (its content in fact), the current file (new, modified, manually merged, deleted) or symbolic link.
When a merge leads to conficts, then you have to fix one by one each unmerged file (with status UU):

  • Edit the file, manually solve the conflicts (look for sequences like <<<<<<<, ======= and >>>>>>>) and save,

  • Use the Add function to stage this changes to the index for the next commit.

Revert

This button reverts the local change on the current entry.
First, a simple screen asks to confirm or cancel the operation, which depends on the type of the current entry, then:

  • If it is a subdirectory (not './' nor '../') then it is deleted, which succeeds only if it is empty.

  • If it is a file or a symbolic link,

    • if unknown by Git, then it is removed,

    • if just added to Git, then it becomes unknown by Git,

    • if just deleted from Git, then it is restored to its last committed content

    • if known by Git and modified, then it is restored to its last committed content,

    • if known by Git and deleted, then it is restored to its last committed content

    • if known by Git and renamed, then the original file is restored to its last committed content and the new one is reset as unknown by Git

    • if up to date in Git, then it is removed from Git

Note
The Revert button is not active on './' and on '../'.
Other actions

XTerm

This button starts a X terminal by launching the command defined in the xterm entry of the configuration file.

Make

This button makes a local compilation by launching the command defined in the make entry of the configuration file.

Commit

This button launches the commit screen that allows commiting the local modifications and pushing them to a remote repository.

Pull

This button launches the pull screen that allows pulling, fetching or checking out a branch from a remote repository;

Tags

This button launches the tags screen that allows managing the tags.

Reset

This button launches the reset menu to reset (hard, mixed or soft) to head or to clean the untracked files and directories of the whole repository, not only the current directory.

Note
It is also possible to reset hard, mixed or soft the whole repository to the head of a given branch (including current branch) through the Reset button of the branches menu. It is also possible to reset hard, mixed or soft the whole repository to a given commit (including current head) through the Reset button of the history menu
Stash

This button launches the stash screen that allows managing the the list of stashes.

Exit

This button makes Agite exit.

6.2. Branches

This menu works on the global repository, not on the local directory.
It allows adding, modifying, checking out a branch, merging a branch into the current, rebasing the current branch along another branch, cherry picking some commits from a branch into the current branch resetting the current branch to the head of another branch.

Current branch and root

This shows the current branch and path of the root of current repository.

List

The list contains the local branches and then the remote tracking bracnhes (in alphanumeric order).

Actions

The possible actions are activated depending on the branch currently left-selected. Criteria of activation are "local or remote tracking", "current or not" "right selection or not". All these actions except the creation lead to return to the directory menu in case of success:

Checkout

Click in the Checkout button to checkout, after confirmation, the head of the branch selected in the list. If the selected branch is a remote tracking branch (and the corresponding local branch does not exist), then it is checked out as a new local branch.
Double clicking on an entry of the list has the same effect.

Hist

This button activates the history menu that shows the history of the root of the branch selected in the list. No modification is allowed in this mode if the selected branch is not the current branch. All the navigation between history and detail menus will apply to the selected branch.

Merge

Click in the Merge button to merge, after confirmation, the branch selected in the list into the current branch.
If the merge does not lead to fast forward, then a new commit is automatically generated with the comment "Merge branch '<branch>'".

TruMerge

Click in the TruMerge button to merge, after confirmation, the branch selected in the list into the current branch, with no fast forward and no commit policy. Then the commit screen is called to allow amending the comment and commiting the result.

Rebase

Click in the Rebase button to rebase the current branch, after confirmation, to the head of the local branch selected in the list. If a branch is right-selected in the list, then it is used as a reference for listing the commits to rebase. Example:

C1 -- C2 -- C5 -- C6 (master)
        \-- C3 -- C4 -- C10 (server)
              \-- C8 -- C9 (client)

If the current branch is client, then a rebase on master (left selection) with no specific reference (no right selection), will rebase C3, C8 and C9 on top of C6:

C1 -- C2 -- C5 -- C6 (master)
        \           \-- C3 -- C8 -- C9 (client)
         \- C3 -- C4 -- C10 (server)

while a a rebase on master (left selection) with the reference server (right selection), will rebase only C8 and C9 on top of C6:

C1 -- C2 -- C5 -- C6 (master)
        \           \-- C8 -- C9 (client)
         \- C3 -- C4 -- C10 (server)

See also the section on rewriting history.

The rebased branch is automatically checked out by this operation and Agite returns to the directory menu.

Note
The Rebase is done by performing automatically successive cherry-picks from the rebased branch to a temporary branch. See the how-to rebase with cherry-pick and the section Error in cherry-pick on how to handle errors during a rebase.
Note
The selection of the commits to pick is automatic (based in current and right/left selected branches). For a manual edition of the selected commits (and for edition, folding options), please use the cherry-pick action instead.
CheryPk

Click on the CherryPk button to launch the menu to cherry-pick commits from the branch left-selected in the list (source) into the current branch (target).
If a branch is right-selected (reference) then the cherries to pick are the ones in the source but not in the reference, otherwise the default reference is the target (see the examples of rebase above).

Reset

This button calls the reset menu to reset (soft, mixed or hard) the repository to the head of the (left) selected local branch.
See also the section on rewriting history.

Create

Enter a name in the text field and click in the Create button, or hit Return, to create a new local branch.

Rename

Enter a new name in the text field and click in the Rename button to rename the local branch selected in the list to the name entered in the text field.

Delete

Click in the Delete button to delete, after confirmation, the branch selected in the list.
Select two branches (one with the right mouse button and the other with the left button) to delete, after confirmation, all the branches between these branches included.

Back

This button returns to the directory menu.

6.3. Bookmarks

General presentation

Locations (directories) can be bookmarked. To bookmark a directory, first move to it through the directory menu, then go in the bookmark menu, then click in the button AddCur. This adds the current directory in the list. Click in Back button to go back to the directory menu. Later on you can open the bookmark menu and double click on the entry, or select it and click on Goto, in order to go back to this directory.

Bookmarks are saved in the configuration file so that they are persistent from one session to another.

List

The bookmark menu shows the current directory and lists the known bookmarks. This list can contain four kinds of entry:

  • Anonymous bookmarks don’t have name. They contain only the path to a directory. Example:

    /home/user/ada
  • Named bookmarks are created like anonymous ones, but with a name previously set in the Name field when clicking in AddCur. The name must comply with the syntax of an Ada identifier (letter [ { [ _ ] letter_or_digit } ]).
    The name appears in parentheses before the path of the bookmark. Example:

    (Reposit) /home/user/ada/reposit
  • Separators are created by first setting a name (in Name), and then clicking in AddSep. The name must comply with the syntax of an Ada identifier.
    This creates a line with dashes and the name. Example:

    ----- Ada -----
  • Blank lines can also be used to separate bookmarks. They are anonymous separators, created by clicking in AddSep with no name set.

Buttons

The buttons AddCur and AddSep insert a named or anonymous (depending on the field Name) bookmark or separator, below the current entry.
This get field Name can scroll horizontally to accomodate to long paths.

The Goto button allows changing the current directory to the bookmark currently selected, and retruns back to the directory menu. It is de-activated on a separator.
Double clicking on the entry has the same effect.

Bookmarks and separators can be organised with the buttons MovUp and MovDwn.

The current bookmark or separator can be edited as follows:

  • To modify the name, first set the new name in the field Name, otherwise leave it empty,

  • Click in the Edit button,

  • Enter or modify the path in the field Path,

  • Click in the OK button or hit the Return key.
    The edition can be cancelled by clicking in the Cancel button or with the Esc key.

Note
As a consequence, it is possible to change a separator into a bookmark and reverse, it is possible to change an anonymous separator or bookmark into a named separator or bookmark, but it is not possible to clear the name of an existing bookmark or separator.

The current bookmark or separator can be deleted with the button Del, after confirmation if it is a bookmark.

Navigation in the list is the same as the navigation in the directory menu, with the mouse wheel, the keyboard and buttons.

The button Back returns to the directory menu without changing the current directory.

Variables

A bookmark path can reference some Environment variables or some predefined variables that Agite maintains automatically.

The predefiend variables are:

  • AGITE_START_DIR: The current directory from which Agite was started (constant).

  • AGITE_INIT_DIR: The initial directory on which Agite was started (constant).

  • AFPX_DATA_DIR: The directory where AFPX configuration files where found (constant).

  • GIT_ROOT_DIR: The root directory of the current repository (updated).

  • AGITE_CUR_DIR: The current directory (updated).

Variable references must be set by editing an exiting bookmark. Modify the bookmark path with any combination of a reference to an environment variable, a reference to a predefined variable, or any fixed string. For example:

<bookmark Name="Agite">/home/${BUILD}/agite>
<bookmark Name="Afpx">${AFPX_DATA_DIR}</bookmark>

You can prevent Agite from expanding a variable by backslashing the delimiters "${" and "}". Example:

<bookmark Name="Afpx">\${AFPX_DATA_DIR\}</bookmark>

6.4. History

On a file, this menu shows the relative path of the selected file, and lists the history of the commits (on the selected branch) that have affected this file.
Git notes are discarded.
The newest release (head) is on top.

It displays on top of screen the current branch, and below, if different, the branch currenly listed.

Below is a "H:" tagged get field in which you can enter (or paste) a up to 40 digits SHA-1 hash value to Search for.

In case of a directory, the menu shows the relative path of the directory and lists the history of the commits that have affected the files of the directory and its sub-directories.

List
Content

The list shows, for each entry, the date of the commit (format YYMMDD:HHMM), a space, then the comment (up to two lines, separated by '$') of the commit.
If the entry is a merge, then the separator between the date and the comment becomes a '>'.

Initial selection

When the history menu is called, the left selection is initially set according to the following criteria, and a character on the top right above the list indicates this criteria:

  • If called from the detail menu, then the current entry is set to the the one that was detailed, and the indicator shows 'C' (for current)

  • Otherwise, if the current directory is the root of the repository (which is always the case when listing the history of a given branch or when setting a tag), then agite tries to set the current entry to the head of the remote of the displayed branch, and the indicator shows 'R' (for remote). If this remote head is not found, then the current entry is set to the current head and the indicator shows '?'.

  • Otherwise the current entry is set to the current head and the indicator is empty.

The indicator is reset when clicking for a left selection or when calling a sub-menu of history.

Navigation

Navigation in the list is the same as the navigation in the directory menu, with the mouse wheel, the keyboard and buttons.

The list can be very long, so there are several extra features on the history list:

  • The position of the current page, in term of percentage of the history, is displayed above the list,

  • The indexes of the left and right selection (see the Diff feature) are also displayed above the list,

  • A hyphen ('-') on the left side of the list indicates the position of the current page, as a scroll bar would do,

  • You can click at a given row in this "scroll bar". The list will move at the page corresponding to where you release the mouse button (and the hyphen will be set to this position).

All

If the history length is reduced by configuration and leads to display only some entries, then this button allows showing all the entries of the history (which can take some time).

Root

If the current history does not apply on the root directory, then this button is active and allows listing the full history of the repository, for the current or selected branch. The history of root is the only way to reorg the current branch or to reset it to a previous commit.

View

Double click on an entry (a commit) or select an entry and click on the View button to view the version of the file that was committed.

When the current history is on a directory this feature is de-activated. Still it is possible to list and view one by one the files of a commit with the detail menu.

Diff

The Diff button shows the differences between commits. When the history is on a directory it applies to all the files of the directory and sub-directories that were affected by the commit(s). In this case the action can lead to launch many differators, so it is started only after confirmation.

Diff can compare two arbitrary commits or show the changes introduced by one commit:

  • Diff between two commits.

    • Left click on an entry of the list. It becomes green and the LeftSel above the list shows the index of this entry from the Head.

    • Right click on an entry of the list. It becomes black and the RightSel above the list shows the index of this entry from the Head.

    • Click on the Diff button. This starts the differator with the right (black) selection as reference and the left (green) selection as the target of the difference. If the history is about a directory several differators may be started.

  • Diff of a commit.

    • Ensure that there is no right selection (no entry on black and RightSel= 0). If there is one then find it and de-select it (by a right click). Alternatively you can right-select any entry and de-select it with a second right click on it.

    • Left click on an entry of the list. It becomes green and the LeftSel above the list shows the index of this entry from the Head.

    • Click on the Diff button. This starts the differator with the version before the selection as reference and the selection as the target of the difference. If the history is about a directory, then several differators may be started.

Detail

This button activates the detail menu on the commit currently (left-)selected in the history.

Restore

This button causes Agite to check that the current file is not locally modified. If not, Agite asks for confirmation then checkouts the file in the version currently (left-)selected in the history. The file will be tagged as 'M' (modified) if this version differs from the one at the head of current branch.
This function is not active on the history of a directory (but restoring a whole commit is possible from the detail menu).

Checkout

This button button launches the checkout menu that allows checking out the selected commit (either in a new branch or as detached from the head).

Note
There is a major difference between the Restore and the Checkout operations.
- Restore overwrites the file with the content that it had in the given commit (it is likely to be tagged as modified in the current repository).
- Checkout checks out the whole repository in the state that it had when the commit was performed.

Reorg

This button launches an interactive rebase of the commits that follow the selected one. This allows splitting, merging, dropping, copying, modifing the comment of these commits.
There is first a check that there is no local change in the repository (they would be lost).
This function is only active when in the root directory of the current branch, so that the current list of commits is exactly the one that will be reorganized.
See also the section on rewriting history.
Upon success or failure, this operation leads to go back to the directory menu (not if the reorg is cancelled).

Note
The Reorg consists in a manual cherry-pick of commits, then an automatic commit of these cherries into a temporary branch, then a hard reset of the current branch to the temporary branch.
See the how-to interactively rebase a branch on itself and the section Error in cherry-pick on how to handle errors during a reorg.
Reset

This button calls the reset menu to reset (soft, mixed or hard) the repository to the (left) selected commit.
See also the section on rewriting history.

Tag

This button button launches the tag menu that allows tagging the selected commit.

Mark

Stores internally (until Agite exits) the hash value of the commit currently left-selected, for later Search.

Search

Searches the commit with the hash value matching the SHA-1 contained in the Hash field. If this field is empty (you can clear it with Ctrl-Suppr) then Agite searches the marked hash instead. If found, this commit becomes left-selected.

Back

This button returns to the directory menu.

Note
The history follows the renaming of the file or directory but the reference name (that is displayed above the history list) is used for the view and diff operations. As a consequence, Agite will fail to show a file, or a difference from a file, if the entry in the history is before a renaming. Still, it is possible to view a file that has been committed then later on renamed, with the following operations:
* Select the commit in the history
* Show the detail of this commit
* Select the file in the detail of the commit (previous name)
* Click in the View button to view the file.

It is not possible to do a diff between two versions of a file if the file has been renamed or moved between the versions.

6.5. Tag

The tag menu allows tagging a commit. It shows the details of the commit, as in the detail menu:

  • The SHA-1 hash of the commit,

  • The date and comment (up to seven lines) of the commit,

  • The list of all the files in the commit, each preceded by a letter M, A or D.
    You can view the corresponding version of a file, or see the difference introduced by this commit on a file.

You can:

  • Mark the current commit for later search in the history menu.

  • Enter the tag name in the Tag name field.

  • If you want to create an annotated tag, then enter the tag comment in the Comment field.

  • Click either in the Tag Annotated or in the Tag Simple to create a tag on the current commit (and go back to the history menu).

6.6. Detail

The detail menu shows the details of a commit or a tag:

It displays on top of screen the current branch, and below, if different, the branch currenly displayed.

Title

In case of a tag, the title recalls the name of the tag (in case of a commit the title is simply "Commit").

Tag information

Then, in case of an annotated tag, the title is followed by the tag information:

  • The date when the tag was created,

  • The first line of the comment of the tag.

Tag and commit information

Then, in both cases, there is the information on the commmit:

  • The SHA-1 hash of the commit, that you can copy into the X11 selection buffer by clicking on PpHash,

  • If the entry is a merge, this is indicated by the word "Merge",

  • The date of the commit, that you can alternatively copy with CpDate,

  • The comment of the commit (up to seven lines), that you can also alternatively copy with CpComm,

  • The list of all the files in the commit, each preceded by a letter:

    • M Modified,

    • T Type modified,

    • A Added,

    • D Deleted.

A specific entry, "/", is added on top of the list, which represents the root of the current repository.

Actions

For all the file entries of the list (not "/"):

  • double clicking on the entry or select the entry and click on View allows viewing the file as it was committed,

  • clicking on the button Diff shows the differences between the version before and in the commit,

  • clicking on the button Hist shows the full history of the file,

  • clicking on the button Restore restores the file from the commit. As in the restore from the history, there is first a check that the file is not locally modified, then a confirmation.

When the "/" entry is selected:

  • clicking on the button Diff launches a differator on each file of the commit (differences brought by the commit), so several differators may be started,

  • clicking on the button Hist shows the full history of the repository,

  • clicking on the button Restore restores all the files of the commit, if none of them is locally modified, and after a confirmation.

In both cases:

  • clicking on the button Mark saves the current commit for later search in the history menu.

Note
Clicking on Hist leads to call a new function that shows the history, as explained in the section on navigation.

6.7. Checkout

The checkout menu allows checking out a commit or a tag.

Note
the checkout operation will be rejected if it leads to overwrite a local modification in the repository.

In case of a commit, the date and comment of the commit are indicated. In case of a tag, the tag name and, if any (annotated tag), the date and the comment of the tag are indicated.

You can (should) enter the name of a new branch into with the checkout is performed. Otherwise the current repository then becomes in detached HEAD state. "You can look around, make experimental changes and commit them, and you can discard any commits you make in this state without impacting any branches by performing another checkout" (another commit earlier in the same branch, or the head of any branch, including the current branch, master…).

Checkout

This button launches the checkout of the tag or commit, in a branch or detached, and returns to the directory menu.

Cancel

This button cancels the checkout (and the branch creation).

6.8. Tags

The tags menu lists the tags of the workdir that match a criteria.

Criteria

The criteria is intially empty, which means "all tags". When the tags menu is launched (from the directory menu), the criteria is used as follows:

  • Either there is a criteria already set (from a previous invocation of the tags menu), then this criteria applies and the matching tags are listed,

  • Or the criteria is empty but the list_tags has been set to true (any casing) in the configuration file, then all the tags are listed,

  • Otherwise no search is performed by default. This is to prevent spending too much time in searching and sorting all the tags.

You can enter a name or a template (like V1.*) in the get area besides the List button or leave it empty (for all the tags). Then you can hit the Return key or click in the List button, which updates the list.

As soon as it is used for searching, the criteria is memorized for further invocations of the menu, until you quit Agite.

List

The list contains the matching tags, sorted by date:

  • Annotated tags are shown with the tag name, tagging date and comment,

  • Non annotated tags are shown with only the tag name,

Create

This button launches the history menu of the root of the repository, which allows selecting a commit and tagging it. No modification (except tagging) is allowed in this mode.

Actions

The possible actions on a tag are:

Detail

This button activates the detail menu on the tag currently (left-)selected in the list.

Checkout

This button button launches the checkout menu that allows checking out the selected tag.

Delete

This button button asks for confirmation, then deletes the selected tag.

Push

This button button launches the push menu that allows pushing the selected tag into a selected remote repository.

Mark

This button saves the hash of the current commit for later search in the history menu.

Back

This button returns to the directory menu.

6.9. Cherry pick

This menu works on the global repository, not on the local directory.
It allows selecting some commits of the selected branch and it applies them into the current branch.
It shows:

Current branch

On the top left is recalled the name of the current branch, into which the selected commits will be applied. In case of a rebase or reorg this is the name of a temporary branch.

Title

The title recalls the name of the source branch from which the commits are selected and the reference branch if it is not the current branch.

Root

The third line recalls the root of the current repository.

List

The list shows the result of 'git cherry', which is the list of commits in the source branch that are not merged into the reference branch. The oldest commits are displayed first, so the list is in the "order of replay".
The first letter of each line describes the status of the cherry:

  • '=' denotes a commit already merged, which cannot be picked nor skipped.

  • ' ' denotes a cherry dropped, which will not be picked.

  • 'P' denotes a cherry picked, which will be applied. If the next not-merged not-dropped cherry is not a squash or a fixup, then the result will be commited with the cherries’s comment.

  • 'W' denotes a cherry picked for wipe-up, which will be applied with an empty comment. This is valid only if the next (not-merged not-dropped) cherry is (possibly after some fixup) a squash.

  • 'R' denotes a cherry picked for rewording, which will be applied then proposed for edition of the comment in the commit menu. It will be possible to edit the comment, commit the change (if the next cherry is not a squash or a fixup) and click on the Done button.

  • 'E' denotes a cherry picked for edition, which will be applied then proposed for full edition of the commit (allowing to modify the comment, to split the commit, to add stashed changes…) in the commit menu. It will be possible to leave some changes not committed, which has a sense if the next cherry is a squash or a fixup.

  • 'S' denotes a cherry picked for squash, which will be applied and folded with the previous cherry. The comment of the cherry will be concatenated to the currently retained comment. If the next cherry is not a squash nor a fixup, then the overall comment will be proposed for edition and the overall result will be committed.

  • 'F' denotes a cherry picked for fixup, which will be applied and folded with the previous cherry. If the next cherry is not a squash nor a fixup, then the result will be committed with the currently retained comment. So the fixup cherry comment is discarded, except if the currently retained comment is empty, in which case the current comment is retained).

By default, all the non-merged commits are selected as picked.

Double-clicking on an entry of the list toggles its selection from dropped to picked and vice versa.

Note
The logic is the same as in Git interactive rebase (except that Git does not implement the Wipe status).
Note
The commits that have already been merged through the 'fast forward' mechanism are not listed at all.
Detail

Click on the Detail button to see the details of a commit, including viewing a file or seeing the differences introduced by this commit, but excluding launching the history menu and excluding restoring files.

Pick, Reword, Edit, Squash, Fixup, Drop

When there is only a left selection in the list, clicking on one of these buttons changes its status, and moves to the next cherry.
When there is a right and a left selection in the list, clicking on one of these buttons changes the status all the commits between the selections included.

Copy

Copy the current cherry.

MovUp and MovDwn

Move up or down in the list the current cherry.

Reset

Click on this button to skip all the commits (except the already merged ones).

Go - Cancel

Click on this button when the selection is completed.
If no commit is selected, then the button is Cancel and Agite returns back in the branches menu.
If some commits are selected, then the button is Go. The picked cherries are then listed in a confirmation screen.
If confirmed, then the picked cherries are applied one by one onto the current branch.
An action to edit or reword launches the commit menu. It is possible to modify some files and the comment, and/or the selection of files, and to make several commits. See the section Cherry-pick advanced how to for more details on how to use the commit menu in this context.

  • Clicking on the Done button goes back to the loop of picking the cherries (possibly with some files not yet committed).

  • Clicking on the Abort button cancels the loop at the current point (see the section Error in cherry-pick for how to restart).

Any error in picking a cherry is reported in a specific screen and the commit menu is launched for manual fix and commit. See the section Error in cherry-pick on how to handle such error.
After completion, Agite returns back in the directory menu.

Note
To cancel the cherry-pick menu, simply ensure that no commit is selected (click on the Reset button) and click on the Cancel button.
Note
If the selection is not valid then this button is de-activated and displays the cause of error:
* FoldPrev if first not merged nor dropped cherry is a squash or a fixup,
* EmptyCmt if a wipe-up not followed by a squash would lead to an empty comment.

6.10. Commit

This menu works on the global repository, not on the local directory.
It shows the list of all the local changes, allows (un)staging them and allows entering a comment for the commit:

Current branch and root

This shows the current branch and the path of the root of the current repository.

Sign

Append the user name and email address to the comment.

Clear

Clear all the comment fields. (You can use Ctrl + Suppr to clear only the current line of the comment.

InsL

Insert a blank line in the comment above the current one. Drops the last line of the comment if it exceeds the maximum number of lines (7).

DelL

Delete the current line of the comment.

MergeL

Merge the current line with the next line. If the resulting line is too long (more than 75 characters), then its tail is dropped.

SplitL

Split in two the current line before the current position (as a key Return would do). Drops the last line of the comment if it exceeds the maximum number of lines (7).

Copy

Copy the text of the comment in the X11 selection buffer.

Comment

You can enter up to 7 lines of up to 75 characters each for the comment.
See section on get fields for details on how to navigate and paste into get fields.

Note
The comment must not be empty when committing.
The text of the comment is saved in the configuration file so that it is persistent from one session to another.
List of changes

This list shows all the current changes in the repository, with 3 letters of status for each file:

  • The first column (S) shows the summary of the status:

    • empty if no changes are staged (e.g. locally modified or deleted),

    • a '*' if some changes are staged and some others are not (also in case of unresolved conflicts),

    • a '+' if all the changes of the file are staged.

    The list is sorted according to these three categories, separated by dummy entries "-----------------".

  • The second column (I) shows the kind of change in the index (that will be committed),

  • The third column (L) shows the kind of change local to the repository (that will NOT be committed).

You can select a file edit it or show its local differences, stage or unstage its changes.

Actions

The possible actions on the list of changes or the comment are:

Double click

A double click on a change toggles the stage status of the entry:

  • if all the modifications of the file are staged (S='+') then unstage these changes,

  • otherwise stage all the changes.

Reread

Normally Agite re-scans the current directory and refreshes the list and status when necessary, and also periodically if the feature is enabled (see period configuration option). This button explicitly refreshes the current list and status of changes.

Stage

Stage (add/rm) the current file (selected in list) or change, and move to next.

Unstage

Unstage (reset) the current file (selected in list) or change and move to next.

StageAll

Stage all the changes that are unstaged. Also proposes to add the untracked (new) files.

Note
The Stage and StageAll buttons also add the files that are in the status U (updated but unmerged), as the Add function.
Note
The Stage, Unstage and StageAll buttons are active only if there are local changes.
Edit

Launch the editor on the current file (selected in list).

Stash

Launch the stash menu, which allows applying a stashed change on the local changes. Beware: applying a stash will merge the changes of a file only if the local changes of this file are staged, otherwise applying the stash will be rejected.

Diff

Show the difference between the current change and the head for the current file (selected in list).

Commit

Commit the staged changes.
If the commit succeeds then the list of changes is updated, otherwise the error is reported through a specific screen.

Note
Ensure to enter a comment before committing, otherwise the operaton will be rejected.
Note
When committing local changes, the text of the Commit button is in red if there are not staged changes (will do an empty commit, after confirmation) or if there are some unstaged changes (will do a partial commit).
To prevent successive empty commits, the button becomes inactive if there is no staged changes (left) after a commit.
Note
When editing commits during a cherry pick session, the Commit button is active only if there are some staged changes (empty commit is forbidden).
Push

This button activates the push menu to push the last commits into a selected remote reference.

Back

This button returns to the directory menu.

6.11. Push

The push menu allows pushing the local commits of the current branch or to push a tag into a selected remote repository.
It shows:

Title

In case of a tag the title recalls the name of the tag.

Current branch and root

This shows the current branch and the path of the root of the current workstree.

List of references

This lists the known remote repositories, from which you can select the target.
If the remote of the current branch is defined, then it is selected by default.

Push

Pushes the local commits of current branch or the tag to the selected remote repository.
After pushing the current branch, Agite returns back to the directory menu, while after pushing a tag it returns back to the tags menu.
Any error is reported through a specific screen.

Push Upstream

Only active when pushing the current branch, allows the creation of the current branch in the remote repository. (If the branch has already been pushed upstream into this repository, then this button has the same effect as Push.)

Push Force

Only active when pushing the current branch, allows forcing the push of current branch in the remote repository. (If local changes do not fast-forward in the remote repository.)

Back

Moves back to the commit menu without pushing.

6.12. Stash

The stash menu works on the global repository, not on the local directory.
The screen shows the list of stashes. Each entry has a stash number, the branch on which the stash was done (or "-" if not known) and the text of the message.

Current branch and root

This shows the current branch and the path of the root of the current repository.

Actions

The possible actions on the list of stashes are:

AddAppl

Stash and re-apply: Enter a message (or name) for the stash, and click in the AddAppl button or press the Return key. Agit stashes the current repository (which performs a git reset --hard), then applies it (which restores the content of the repository), then returns to the directory menu.
The new stash has been inserted in the list.

Note
You can un-apply this stash (git reset --hard) by selecting the entry "/" of the directory list and cliking on the revert button.
AddReset

Stash and reset: Enter a message (or name) for the stash and click in the AddReset button. Agit stashes the current repository, which performs a git reset --hard, then returns to the directory menu.
The new stash has been inserted in the list.

Apply

Apply a saved stash: Applies the stash currently selected in the list and returns to the directory menu. A double click on an entry has the same effect.

Pop

Delete and apply a saved stash: After confirmation, applies the stash currently selected in the list, removes it from the list and returns to the directory menu.

Del

Delete a saved stash: After confirmation, deletes (drops) the stash currently selected in the list.

Rename

Rename a saved stash: Select a stash, enter a message (or name) for the stash and click in the rename button. The entry selected is renamed after confirmation (and moved at the top of the list). The branch information of the stash is lost.

Back

This button returns to the directory menu.

Note
If the new name is empty:
* AddAppl and AddReset let GIT set the default name (short SHA and comment of the head the of the current branch),
* Rename sets a default name ("-").

6.13. Pull

The pull menu allows pulling the current branch (fetching and merging) or fetching only or checking out another branch from a remote repository.
This is achieved through two successive screens.

6.13.1. Remote selection

This screen allows selecting the remote repository from which to pull, fetch or checkout.
It shows:

Current branch and root

This shows the current branch and the path of the root of the current repository.

List of remote repositories

This lists all the known remote repositories. If the remote of the current branch is defined, then it is selected by default.

Fetch

This button asks for confirmation then fetches all the known remote branches from the the selected remote.

Prune

This button prunes from the local repository all the tracking branches that refer to the selected remote and that do not exist (any more) in this remote.

OK

Validates the selection of remote and activates the branch selection for selecting the branch to pull, fetch or checkout.

Back

Moves back to the directory menu without pulling.

6.13.2. Branch selection

This screen allows selecting the branch to pull, fetch or checkout from the repository previously selected.
It shows:

Current branch and root

This shows the current branch and the path of the root of the current repository.

Selected remote

Below the title is displayed the remote (previously selected).

List of branches

This lists the branches in the the remote, from which you can select the one to pull, fetch or checkout.
If it exists, the current branch is selected by default and will be pulled. If you select another branch it will be fetched or checked out.

Main action: Pull/Fetch/Checkout

This button shows and launches an action, depending on the remote branch currently selected in the list:

  • Pull: when the remote branch selected matches the current branch, pulls the remote branch,

  • Fetch: when the remote branch matches another local branch, fetches the remote branch,

  • Checkout: when the remote branch does not match any local branch, fetches the remote branch then checks it out.

Alternate buton: Fetch

When the main action is Pull (the selected remote branch matches the local current branch) or Checkout (the selected remote branch does not exist locally), this button is active and allow only fetching the remote branch into the local tracking branch, for a later manual merge.

If there is no error then Agite returns back to the directory menu, otherwise the error is reported through a specific screen.

Back

Moves back to the remote selection menu without action.

6.14. Reset

This menu has three modes:

Called by the branches or the history menu,

it allows to reset the current repository to a branch or to a commit.
The reset can be:

  • Soft: reset only the head of current branch (not the index nor the worktree),

  • Mixed: reset the head and the index (not the worktree),

  • Hard: reset the head, the index and the worktree,

  • and it is also possible to Cancel.

If cancelled, it goes back to the calling menu, otherwise to the directory menu.

Called by the directory menu,

it allows the same kinds of reset as above, but to the head of current branch. It also allows to Cleanup from the current repository the untracked files and directories,

It goes back to the directory menu.

Called by the commit menu during a cherry pick,

it allows to hard reset the current repository to head (which resets the remaining changes of the current commit).

It is also possible to cancel and return to the commit menu of the cherry pick.

7. Cherry-pick advanced how-to

7.1. Use-cases

  • Fold several cherries into one, update the last comment

    • Pick the first cherry to fold,

    • Fixup all the other cherries to fold except the last one,

    • Squash the last cherry to fold,

    • Check/modify the comment of the last commit, Commit then click on Done.

  • Change the comment of a cherry and fold it with with several following fixes

    • Reword the first cherry to fold,

    • Fixup all the other cherries to fold,

    • Modify the comment of the first commit then click on Done.

  • Fold some local changes with the last cherry

    ⇒ If none of the locally changed files are modified in the cherry, or if they are to be folded

    ⇒ If some of the locally changed files are not to be folded and are already modified in the cherry

  • Fold several cherries, discard the comment of the first cherry

    • Wipe-up the first cherry to fold,

    • Squash all the other cherries,

    • Check/modify the comment of the last commit, Commit then click on Done.

  • Split a cherry into several successive commits

    • Edit the cherry,

    • In the commit screen, set the comment and stage the files for the first commit, then Commit. Set the comment and stage the files for the second commit, then Commit… Finally, click on Done.

  • Remove some files from a cherry

    • Edit the cherry,

    • In the commit screen, leave staged the files to keep (unstage the files, to remove), commit the change,

    • Call the stash menu and AddReset the remaining files into a new stash,

    • Click on Done.

    • During or after the cherry-pick operation, you can reuse or delete the stash.

  • Split a cherry into two commits separated by already existing commits

    • Edit the cherry,

    • Copy the cherry,

    • Move both copies at the proper position in the list,

    • In the first commit screen, set the comment and stage the files for the first commit, then commit and click on the Done button,

    • In the second commit screen, set the comment and stage the remaining files, then Commit and click on Done.

  • Rebase a branch along another

    • On the target branch, create a Tmp branch,

    • Cherry pick from the source branch into the Tmp branch, pick all,

    • Hard reset the rebased branch to the Tmp branch,

    • Delete the Tmp branch.

      Note
      This is exactly how the rebase is performed.
  • Interactively rebase a branch on itself

    • In the history menu on the rebased branch, select the commit that is just before the first commit to rebase, and check out it as a Tmp branch,

    • Cherry pick from the original branch into the Tmp branch, modify the selection as necessary,

    • Hard reset the rebased branch to the Tmp branch,

    • Delete the Tmp branch.

      Note
      This is exactly how the reorg is performed.
      As a consequence, if no commit is selected during the cherry pick, then the reorg is cancelled: A reorg that only drops several last consecutive commits is achieved through a hard reset to the first commit that has to be kept.
Note
Rebase and reorg create a temporary branch named "{Agite}@"<source>".Tmp". If this branch already exists then another ".Tmp" is appended, and so on.

7.2. Handling error and restarting

If a cherry fails to be applied, it is very likely due to a confict in the merge, so the commit screen is called for manual resolution. Also, if a cherry is selected for Edit (or Reword), then the commit screen is called within the loop of cherry-picks.
At this point there are two possibilities: continue or abort.

7.2.1. Fix, commit and continue

Hopefully you can use the file edition and staging in order to resolve the conflict. You should then commit the changes and then click on the Done button. The loop will continue processing the remaining cherries.

7.2.2. Abort

If you need more tools or more time to solve the conflict, then you can click on the Abort button to cancel the commit and exit the the loop of cherry picking. You are then back in the directory menu, from which you should fix the conflict and commit the result. Beware that you might be on a temporary branch.
Restarting the loop depends on wether the failure occured during a rebase or reorg, or during a cherry-pick.

Restart a rebase or reorg

The current temporary branch contains the cherries picked so far, including the last manual commit.

  • You may launch a rebase or reorg of the same branch, and along the same branch or from the same reference as the previously interrupted rebase or reorg. Then Agite proposes to continue the rebase or reorg. You will be prompted to restart interactively the cherry-pick from the rebased branch into the temporary branch (you may probably need to skip (drop) the cherry that was committed manually).

  • Alternatively, you can launch a cherry-pick from the rebased or reorganized branch into the current temporary branch, and complete the process manually as described below.

Restart a cherry-pick

If you launch a cherry-pick from the same branch and to the same branch as the previously interrupted cherry-pick, then Agite proposes to restart the cherry-pick. The previous selection of cherries to drop or pick for edit/fixup/commit is restored.

Note
If you launch any other rebase, reorg or cherry-pick or if you quit Agite, then the interupted cherry-pick or rebase cannot be restarted automatically.
In case of a reorg or rebase, the temporary branch, named "{Agite}@"<source>".Tmp', remains (with some commits already applied). You can complete the cherry-pick manually on it, then hard-reset the rebased branch on it, then delete it, as described in the rebase and the reorg use-cases.

8. Rewriting history

Rewriting the history can have serious consequences if you modify commits that have already been published, and have been pulled by some other repositories.
The four functions of Agite that alter the history are:

  • The reset functions of the branches and of the history menus rewrites the history of the reset branch,

  • The rebase function of the branches menu rewrites the history of the rebased branch (which is reset),

  • The reorg function of the history menu rewrites the history of the current branch (which is reset).

The confirmation menu for these actions warns you (in red) that the history will be rewritten.
Besides, the history menu on root sets the initial entry to the head of the corresponding tracking branch, which should be a safe reference for a reorg or reset. When the reference is set to below (before) the head of the remote, then these both buttons become red.
Similarly, when they are active the rebase and reset buttons of the branches menu are in red (except reset to current branch).

Note
The following operations do not rewrite the history:
* The cherry-pick function, because it applies commits to the target branch, which evolves naturally.
* The reset function of the directory menu, because it resets the repository to the head of the current branch (which is the head of the history).
* The reset to the first commit of the list of the history menu, because it resets to the head of the current branch.
* The reset to the current branch of the branches menu, because it resets to the head of the current branch.

9. Scope of the operations

Each of the operations described above operates on a given scope, which is summarized hereafter.

9.1. Current directory

The following functions and screens apply to the current directory or to the selected file or directory:

  • Reread button rereads the current directory

  • Quick search button searches a file or a directory in the current directory

  • Make button launches make in the current directory

  • Edit button edits the selected file

  • Diff button shows the differences on the selected file or directory

  • Hist button shows the history of the selected file or directory

  • Add and Revert buttons add or remove the selected file or directory

  • Restore button (of the detail menu) retrieves the selected file or all the files of the commit

9.2. Current repository

The following functions and screens apply to the current repository:

  • Branch screen allows several operations on branches on the current repository and ancestors, including History, Merge, Rebase and Cherry pick

  • Root button moves to the root directory of the current repository,

  • Commit screen allows commiting the files modified within the current repository

  • Push screen allows allows pushing commits on the current repository

  • Pull screen pulls branches of the current repository

  • Tags screen lists the tags of the current repository

  • Checkout button (of the history menu or of the tags menu) checks out the commit in the current repository

  • HReset button (of the history menu or of the branches menu) resets the current repository to the state of the commit or branch

  • Reorg button (of the history menu) makes a rebase of the current branch, applying to the whole repository

  • Stash screen saves and restore stashes on the current repository

  • Tag tags a commit of the current repository

  • Detail shows the details of a commit on the current repository

  • Clean and Reset, clean or reset the whole repository

9.3. Anywhere

The following operations allow changing the current directory with no limitation:

  • Go button moves to the specified directory

  • Dir Up button moves to parent directory

  • Bookmarks menu handles bookmarks of directories

  • PushD and PopD buttons push and pop directories

  • Xterm button starts a terminal in the current directory, then one can change its current directory

10. Interfaces with Git

This section lists the commands and arguments passed to Git. This requires git version 1.7.0 or above:

  • A function gets Git version by calling git --version,

  • A function lists local files by calling git ls-files and git status -- porcelain .,

  • A function lists all changes by calling git status -- porcelain .,

  • A function lists the status of a file by calling git status -- porcelain <file>,

  • A function lists the commits on a dir or file by calling git log --date=iso --full-history [ --sparse ] [ -n <max> ] [ <branch> ] [ -- <dir_or_file> ],

  • A functions gets the hash of the last commit by calling git log --pretty=format:"%H" -n -1 — <pwd>,

  • A function gets general information on a commit by calling git log --date=iso -n 1 <HSA1_hash> --,

  • A function gets the details of a commit by calling git log --name-status --date=iso -n 1 <HSA1_hash> --,

  • A function lists the remote repositories by calling git remote,

  • A function extracts a given version of a file (in a commit by calling git show <HSA1_hash>:<file> > <file>,

  • A function launches the differator on a modified file (versus Head) by calling git difftool -y -x <differator> HEAD -- <file>,

  • A function lauches the differator between two versions of a file (or dir) by calling git difftool -y -x <differator> <ref_HSA1_hash> <comp_HSA1_hash> -- <file>,

  • A function reverts the local changes of a file by calling git checkout HEAD -- <file>,

  • A function resets the staged sgtatus of a file by calling git reset -- <file>,

  • A function resets the repository to a commit or branch, by calling git reset --hard <ref>,

  • A function mixed or soft resets the repository to head, by calling git reset --mixed | --soft,

  • A function cleans untracked files and directories by calling git clean -d -f,

  • A function globally checks out a given commit or branch by calling git checkout [ -b <branch> ] <ref>,

  • A function stages a change of a file by calling git add -- <file>,

  • A function removes a file from the index by git rm -- <file>,

  • A function commits the local changes by calling git commit --allow-empty -m "<comment>",

  • A function pushes the local commits of current branch or a tag by calling git push [ --set-upstream ] [ --force ] <remote> [ <tag> ],

  • A function fetches or pulls the current branch by calling git fetch --tags <remote> <branch> or git pull --tags <remote> <branch>,

  • A function prunes useless remote branches by calling git remote prune <remote>,

  • A function gets the name of current branch by calling git branch,

  • A function lists the local branches by calling git branch or lists the remote tracking branches by calling git branch -r or lists both by calling git branch -a,

  • A function gets the name of a remote tracking branch by calling git branch -vv,

  • A function lists the branches of a remote reference by calling git ls-remote --heads <reference>,

  • Three functions create/rename/delete a branch by calling git branch [ -m | -d ] <name> [<new_name>],

  • A function merges a branch into current by calling git merge [ --no-commit | [ -m <comment> ]] [ --no-ff ] <branch>,

  • A function gets the user name and email by calling git config user.name and git config user.email,

  • A function gets the list of stashes by calling git stash list,

  • A function saves the current stash by calling git stash save <message>,

  • Three functions apply/pop/drop a stash by calling git stash apply/pop/drop -q stash@{<num>},

  • A function stores a dropped stash (for renaming) by calling git stash store -m [ - | <name> ] -q <ref>,

  • A function shows a tag by calling git show --date=iso --quiet -s <tag> --,

  • A function lists the tags by calling git tag [ -l <template> ],

  • A function deletes a tag by calling git tag -d <tag>,

  • A function adds a tag by calling git tag [ -a -m <comment> ] <tag> <ref>,

  • A function lists the cherry commits of reference branch versus a target branch by calling git cherry <target> <reference>,

  • A function cherry picks some commits by calling git cherry-pick --ff { <HSA1_hash> },

  • A function checks if current repository is bare by calling git rev-parse --is-bare-repository.