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.
NoteAgite 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 XML 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.
NoteAt 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 XML configuration file, which contains the fields:
- 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.
NoteThis 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).
- patch
-
This defines the command to be launched for making a patch file. The command will be called with the patch name (as first argument), then the first Hash, then the last Hash. The command shall create a patch file, named "$1" of commits "$2..$3".
- 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 modifies 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.
NoteAgite also 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.
|
Note
|
The DTD file agite.dtd must be located according to the 'DOCTYPE'
directive of the configuration file. |
|
Note
|
When editing the configuration file in order to modify these parameters,
you should ensure that: * Agite is not running or at least you are not using it (changing current directory or modifying the comment of the commit, which might revert your changes), * You don’t add XML comments (Agite would remove them), * The configuration file remains compliant with the DTD agite.dtd. |
4.2. Agite persistent data
Agite also uses the configuration file to store information from one invocation to another.
- 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.
-
- 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.
- comment
-
Agite saves the text of the current comment of the commit, so that it is retrieved from one session to another.
NOTE If necessary, you may edit the configuration file and 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 configuration file remains compliant 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 is named 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
-
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 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
-
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 '^' instead of 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 another screen oir command…
5.4. Whole screen
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).
-
Tree: This shows the Git history of a file or directory as a tree with the different branches.
-
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 stageing 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.
-
Patch: This allows creating a patch file to export several commits.
-
Reflog: This menu allows listing and managing the references along a given branch (git reflog).
+-----------+
/->| Bookmarks | +--------+
/ +-----------+ /------>| Reflog |------+---+
/ / +--------+ | |
/ +----------+/ +------------+ | |
/----->| Branches |--+------>| CherryPick |--+ |
/ +---+------+ / +------------+ | |
/ | / | |
/ | / +-----+ | |
/ | /---------->| Tag | | |
/ V / +-----+ | |
/ +-------+-+ +--------+ | |
/------------>| History |<-+-----+->| Detail |<-----+ |
/ +-------+-+ \ / +--------+ | |
/ +------+ \ \ / +----------+ | |
/----------------| Tags |--+-----+---->| Checkout |<--(|(--+
/ +------+ \ +----------+ |
+---------- +/ +-------+ \ +------+ |
| Directory |------------------>| Commit|----+------->| Push | |
+---------- +\ +---+---+<-\ +------+ |
\ | \ |
\ V \ |
\ +-------+ \-----------------------+
\------------->| Stash | |
\ +-------+ |
\ +------+ |
\---------->| Pull | |
\ +------+ |
\ +------+ |
\------->| Tree |------------------------------+
+------+
+-------+ +-------+
| Reset | | Patch |
+-------+ +-------+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 Tree menu is like the History menu except that it only calls the Detail menu, and without allowing modifications nor tagging. 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 CherryPick menu calls the Detail menu, but without allowing modifications. The CherryPick menu calls the Commit menu in a specific mode where is does the Reflog menu calls the Details menu without allowing modifications nor tagging. not allow to call the Push menu. The Reset menu is called by the Directory, the History, the Branch, the Reflog and the Commit menus. The Patch menu is called by the History menu. |
|
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:
- 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).
- Root
-
This line shows the root directory of the current Git repository. Clicking in this field changes the current directory to the root.
- Changes
-
At the right of the root directory, a red star '*' may appear to indicate that the current repository contains local modifications compared to the top of the current branch (new files, modifications, deletions…). You can use commit menu to see and manage these changes.
- Go
-
This line shows the current directory. This field can be modified by:
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.
-
- 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 status in Git index and its 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. |
- 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
-
NoteThe Revert button is not active on './' and on '../'. -
- 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.
NoteIt 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.
This shows the current branch and path of the root of current repository.
The list contains the local branches and then the remote tracking branches (in alphanumeric order).
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 menu 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. - Reflog
-
This button calls the xref:XRefelog menu to display the reflog of the (left) selected branch and allowing checkout or reset to a reference.
- 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.
This button returns to the directory menu.
6.3. Reflog
This menu shows the successive references of the selected branch. Each entry provides the cause of the change (either acommit, a checkout, a reset… ) and additionnal information (comment of the commit, Hash…)
The header shows the current branch and repository, and the name of the branch from which are extracted the references.
Below is a "H:" tagged get field in which you can enter (or paste), up to 128 hexadecimal digits, a hash value to Search for.
The list shows for each reference:
-
The date
-
Two letters of operation
-
Co for Commit
-
Ck for Checkout
-
Re for Reset
-
Cp for Cherry-Pick
-
Me for Merge
-
Pu for Push
-
-
The comment
The Detail button shows the details of the (left) selected reference.
The Checkout button calls the Checkout menu in order to checkout the selected reference (as a new branch).
The Mark button stores the hash value of the reference currently left-selected, for later Search of reference.
|
Note
|
Agite store internally the hash value is stored internally until it exits. The menus reflog, history and tree share this reference for marking and searching. |
Searches the reference with the hash value matching the hash 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 reference becomes left-selected.
|
Note
|
Several references may correspond to the same Hash. Successive searches will show the matching references one after the other. |
The Reset button calls the Reset menu in order to hard reset the current branch to the selected reference.
the Delete button deletes, after confirmation, the reference currently selected.
6.4. Bookmarks
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.
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.
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.
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.5. History
This menu shows the relative path of the selected file or directory,
and lists the history of the commits (on the selected branch) that have
affected this file or directory.
Git notes are discarded.
The newest release (head) is at the top.
The menu displays on top of screen the current branch, and below, if different, the branch currenly listed.
In case of a directory, the menu shows the relative path of the directory.
In case of a file, it shows the relative path of the file. If the currently
(left) selected commit is after (below) a commit in which the file was
renamed, then the original name in the selected commit is shown, preceeded by
"- ".
Below is a "H:" tagged get field in which you can enter (or paste), up to 128 hexadecimal digits, a hash value to Search for.
- Content
-
The list shows, for each commit, the date (format YYMMDD:HHMM), a space, then the comment (up to two lines, separated by a space).
If the commit is a merge, then the separator between the date and the comment becomes a '>'.
If the commit contains a renaming of current file, then the separator becomes a '+'. - Initial selection
-
When the history menu is called, the left selection is initially set to the current item in the calling menu, if any, and an indicator at the top right of the list shows C. See also the button RemHd.
+ 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 ('-' if the list fits in one page),
-
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).
-
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).
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, to reset it to a previous commit, or to make a patch with several commits.
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.
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.
-
This button activates the detail menu on the commit currently (left-)selected in the history.
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. Due to renaming, the restored file can also be tagged as '?'
(unknown).
This function is not active on the history of a directory (but restoring a
whole commit is possible from the detail menu).
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. |
This button launches an interactive rebase of the commits that follow (are
above) the selected one. This allows splitting, merging, dropping, copying,
swapping and 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.
A detailed description of the steps and possible actions will be found in the
section about cherry-pick of commits.
|
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 also the section on rewriting history. In case of problem, 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. |
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.
This button button launches the tag menu that allows tagging the selected commit.
-
lists the commits between the selection and the right-selection (sorted in chronological order) if on root, otherwise lists the current selection,
-
provides a button Delete to delete the current item from the list (when it is the first or the last),
-
provides a button Today to list the commits of the current day, when on root,
-
provides a button Reset to reset the list to the initial selection,
-
allows entering a patch file name (without space),
-
and allows clicking in the OK button.
It will then launch the patch command with the patch file name, and the Hash values of the first and of the last commit. It will then display the output or the error message of the command.
Stores the hash value of the commit currently left-selected, for later Search.
Searches the commit with the hash value matching the hash 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.
|
Note
|
Agite store internally the hash value is stored internally until it exits. The menus reflog, history and tree share this reference for marking and searching. |
Moves the current (left) selection in the list to the head of the remote (parent) branch. In this case, the indicator shows R. Also, the buttons Reorg and Reset become red when the current selection is below (older) than the head of the remote branch. If the head of the remote cannot be identified then the inidicator shows ?.
This button returns to the directory menu.
6.6. Tree
It behaves like the history menu regarding:
-
Limitation of the number of entries to history length,
-
Switching to Root and back,
-
Navigation in the list, including the scroll bar,
-
Marking and searching for a hash value,
-
Viewing the version of a file committed,
-
Viewing the differences introduced by a commit or between two commits,
-
Viewing the details of a commit (but disallowing Restore).
It does not support the other functions of the history menu (Restore, Checkout, Reorg, Reset, Tag and Patch) and it does not show the renaming of files.
6.7. Tag
The tag menu allows tagging a commit. It shows the details of the commit, as in the detail menu:
-
The 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.8. Detail
It displays on top of screen the current branch, and below, if different, the branch currenly displayed.
In case of a tag, the title recalls the name of the tag (in case of a commit the title is simply "Commit").
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.
Then, in both cases, there is the information on the commmit:
-
The 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 indicating the file status:
-
A = Added,
-
C = Copied,
-
D = Deleted,
-
M = Modified,
-
R = Renamed,
-
T = Type modified,
-
U = Unmerged,
-
X = Unknown,
-
B = paring broken.
-
A specific entry, "/", is added on top of the list, which represents the root of the current repository.
After each renamed entry (containing the initial name) a specific entry is inserted, with the status + and the new name.
|
Note
|
Some file statuses above may not all be implemented by old versions of GIT. |
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:
|
Note
|
Clicking on Hist leads to call a new function that shows the history, as
explained in the section on navigation. If the current selection is a file that has been renamed after the current commit, then the history will stop at the commit where the file has been renamed. |
6.9. Checkout
|
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…).
This button launches the checkout of the tag or commit, in a branch or detached, and returns to the directory menu.
This button cancels the checkout (and the branch creation).
6.10. Tags
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.
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,
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.
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.
This button returns to the directory menu.
6.11. 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:
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.
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.
The third line recalls the root of the current repository.
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 and not committed. This is valid only if the next (not-merged not-dropped) cherry is (possibly after some other wipe) a fixup or a squash.
-
R denotes a cherry picked for rewording, which will be applied then proposed for modification 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 modification 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. The comment of the fixup cherry 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 action). |
|
Note
|
The commits that have already been merged through the 'fast forward' mechanism are not listed at all. |
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.
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 the current cherry.
Move up or down in the list the current cherry.
Click on this button to skip all the commits (except the already merged ones).
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 (and possibly squash 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 or a fixup would lead to an empty comment. |
6.12. Commit
This menu works on the global repository, not on the local directory.
It shows the list of all the local changes, allows (un)stageing them and allows
entering a comment for the commit:
This shows the current branch and the path of the root of the current repository.
Copy the text of the comment in the X11 selection buffer.
Append the user name and email address to the comment.
Clear all the comment fields. (You can use Ctrl + Suppr to clear only the current line of the comment.
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).
Delete the current line of the comment.
Merge the current line with the next line. If the resulting line is too long (more than 75 characters), then its tail is dropped.
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).
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 can be retrieved from one session to another (with the Prev button). |
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, then edit it, show its local differences, stage or unstage its changes.
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 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). |
This button activates the push menu to push the last commits into a selected remote reference.
This button returns to the directory menu.
6.13. Push
The push menu allows pushing either the local commits of the current
branch or a tag, into a selected remote repository.
It shows:
In case of a tag the title recalls the name of the tag.
This shows the current branch and the path of the root of the current workstree.
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.
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.
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.)
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.)
6.14. 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.
This shows the current branch and the path of the root of the current repository.
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 with the option Hard of the reset menu. 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.
This button returns to the directory menu.
|
Note
|
If the new name is empty: * AddAppl and AddReset let GIT set the default name (short hash and comment of the head the of the current branch), * Rename sets a default name ("-"). |
6.15. Pull
The pull menu allows pulling the current branch (fetching and merging) or
only fetching it, or checking out another branch from a remote repository.
This is achieved through two successive screens.
6.15.1. Remote selection
This shows the current branch and the path of the root of the current repository.
This lists all the known remote repositories. If the remote of the current branch is defined, then it is selected by default.
This button asks for confirmation then fetches all the known remote branches from the the selected remote.
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.
Validates the selection of remote and activates the branch selection for selecting the branch to pull, fetch or checkout.
Moves back to the directory menu without pulling.
6.15.2. Branch selection
This screen allows selecting the branch to pull, fetch or checkout from the
repository previously selected.
It shows:
This shows the current branch and the path of the root of the current repository.
Below the title is displayed the remote (previously selected).
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.
This button shows and launches an action, depending on the remote branch currently selected in the list:
-
Pull: when the selected remote branch matches the current branch, pulls the remote branch,
-
Fetch: when the selected remote branch matches another local branch, fetches the remote branch,
-
Checkout: when the selected remote branch does not match any local branch, fetches the remote branch then checks it out.
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), then this button is active and allows 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.
Moves back to the remote selection menu without action.
6.16. Reset
it allows resetting 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 then it goes back to the calling menu, otherwise it returns to the directory menu.
it allows the same kinds of reset as above, but to the head of current branch. It also proposes to Cleanup from the current repository the untracked files and directories,
It goes back to the directory menu.
it allows hard resetting 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
|
Note
|
During the loop of cherry-pick, the comment of the commit is automatically propagated from a commit to the next one when this is relevant. |
7.1. Use-cases
-
Fold several cherries into one, keep the first commit (case of a modification with accurate comment, then fixes)
-
Pick the first cherry to fold,
-
Fixup all the other cherries to fold.
-
-
Fold several cherries into one, keep the last commit (case of some steps of a modification, then a final commit with accurate comment)
-
Wipe all but the last commit to fold,
-
Fixup the last commit to fold.
-
-
Fold several cherries into one, keep and update the first and last comments
-
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 global 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
-
Stash and reset the local changes,
-
Move to root, reorg from the one but last commit, and select the commit for Edition,
-
In the commit menu, apply the stash, stage the changes to fold, click on Commit,
-
Click on reset then on Hard,
-
Back in the commit menu, click on Done.
-
Finally, pop the stash.
The remaining changes are locally to be committed.
⇒ If some of the locally changed files are not to be folded and are already modified in the cherry
-
Stash and apply the local changes (e.g. as "Global"),
-
Revert one by one the changes not to be folded,
-
Stash and reset the remaining changes (e.g. as "Fold"),
-
Launch the reorg as above,
-
In the commit menu, pop the stash "Fold", stage all the changes, click on Commit then on Done,
-
Finally, pop the stash "Global".
The remaining changes are locally to be committed.
-
-
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.
-
-
-
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.
NoteThis 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.
NoteThis 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.
-
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, strashing and stageing 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 likely are 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, the history and the reflog menus rewrite 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 Delete function of the reflog menu also rewrites the history.
The confirmation menu for these actions alerts you (in red) that the history
will be rewritten and has been pushed, or warns you (in orange) that the
local history will be modified.
Besides, the "RemHd" button of the history menu sets the
current 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
-
Reset button (of the directory menu, the history menu or 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
-
Reflog manages the references in 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 checks if current repository is bare by calling git rev-parse --is-bare-repository.
-
A function lists local files by calling git ls-files and git status --porcelain --untracked-files=all .,
-
A function lists local changes by calling git status --porcelain --untracked-files=all <path> | ".",
-
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 [ -n <max> ] [ --sparse ] [ --name-status ] [ <branch> ] [ -- <dir_or_file> ],
-
A fuction lists the tree of a dir or file by calling 'git log --graph --oneline --all --full-history [ -n <max> ] --date-order --no-abbrev-commit <path>,
-
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 -m <HSA1> --,
-
A function gets the details of a commit by calling git log --name-status -M --date=iso -n 1 <HSA1> --,
-
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>:<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>:<ref_file> <comp_HSA1>:<comp_file>
or git difftool -y -x <differator> <ref_HSA1> <comp_HSA1> — <ref_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 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 name of a remote tracking branch by calling git branch -vv,
-
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 --allow-empty [ --ff | --no-commit ] <HSA1>,
-
A function lists the references of a given branch by calling git reflog --no-abbrev-commit --date=iso <branch>,
-
A function deletes a given reference by calling git reflog delete --rewrite <reference>.