SmartGit STUDY 2

The Index

The Index is an intermediate cache for preparing a commit. With SmartGit, you can make heavy use of the Index, or ignore its presence completely - it's all up to you.

The Stage command allows you to save a file's content from your working tree in the Index. If you stage a file that was previously version-controlled, but is now missing in the working tree, it will be marked for removal. Explicitly using the Remove command has the same effect, as you may be accustomed to from SVN. If you select a file that has Index changes, invoking Commit will give you the option to commit all staged changes.

If you have staged some file changes and later modified the working tree file again, you can use the Discard command to either revert the working tree file content to the staged changes stored in the Index, or to the file content stored in the repository (HEAD). The Changes view of the SmartGit project window can show the changes between the HEAD and the Index, between the HEAD and the working tree, or between the Index and the working tree state of the selected file. Individual change hunks can be staged and unstaged there.

When unstaging previously staged changes, the staged changes will be moved back to the working tree, if the latter hasn't been modified in the meantime, otherwise the staged changes will be lost. In either case, the Index will be reverted to the HEAD file content.

Important Git Commands

This chapter gives you an overview of important SmartGit commands.

Synchronizing with Remote Repositories

Synchronizing the states of local and remote repositories consists of pulling from and pushing to the remote repositories. SmartGit also has a Synchronize command that combines pulling and pushing.

Pull

The Pull command fetches commits from a remote repository, stores them in the remote branches, and optionally 'integrates' (i.e. merges or rebases) them into the local branch.

Use Remote|Pull (or the corresponding toolbar button) to invoke the Pull command. This will open the Pull dialog, where you can specify what SmartGit will do after the commits have been fetched: Merge the local commits with the fetched commits or rebase the local commits onto the fetched commits. In the latter case, you can merge or rebase by hand, as explained in Merge and Rebase, respectively. These options are meaningless, if you select to Fetch Only.

The Pull dialog allows you to set your choice as default for the current branch. To change the default choice for new branches, go to Repository|Settings.

If a merge or rebase is performed after pulling, it may fail due to conflicting changes. In that case SmartGit will leave the repository in a merging or rebasing state so you can either resolve the conflicts and proceed, or abort the operation. See Merge and Rebase for details.

Pulling tags

By default, Git (and hence SmartGit) will only pull new tags, but don't update possibly changed tags from the remote repository. To have tags updated as well, you have to configure --tags as tagopt for your remote.

Example

To update tags when pulling from origin, your .git/config file should look like the following ('... ' represents your already currently set values):

[remote "origin"] fetch = ... url = ... tagopt = --tags

Push

The various Push commands allow you to push (i.e. send) your local commits to one or more remote repositories. SmartGit distinguishes between the following Push commands:

Push Pushes all commits in one or more local branches to their matching remote branches. More precisely, on the Push dialog you can choose between pushing the commits in the current branch to its matching remote branch, and pushing the commits in all local branches with matching remote branches to said remote branches. A local branch `matches' a remote branch if the branch names match, e.g. `master' and `origin/master'. With this Push command you can push to multiple repositories in a single invocation. SmartGit will detect automatically whether a forced push will be necessary.
Push To Pushes all commits in the current branch either to its matching branch, or to a ref specified by name. With the Push To command you can only push to one remote repository at a time. If multiple repositories have been set up, the Push To dialog will allow you to select the remote repository to push to. Also, the Push To command always allows to do a forced push, what can be convenient. This is necessary when pushing to a secondary remote repository for which forcing the push may be necessary while it is not when pushing to the primary remote repository (i.e. the one which is considered by SmartGit's forced push detection). You can also invoke Push To on a remote to push (or synchronize) all branches from the selected remote to another remote.
Push Commits Pushes the selected range of commits from the Outgoing view, rather than all commits, in the current branch to its tracked remote branch.

If you try to push commits from a new local branch, you will be asked whether to set up tracking for the newly created remote branch. In most cases it is recommended to set up tracking, as it will allow you to receive changes from the remote repository and make use of Git's branch synchronization mechanism (see Branches).

The Push commands listed above can be invoked from several places in SmartGit's project window:

Menu and toolbar In the menu, you can invoke the various Pull commands with Remote|Push, Remote|Push To and Remote|Push Commits. The first two may also be available as toolbar buttons, depending on your toolbar configuration. The third command is only enabled if the Outgoing view is focused.
Repositories view You can invoke Push in the Repositories view by selecting the open repository and choosing Push from the context menu.
Branches view In the context menu of the Branches view, you can invoke Push and Push To on local branches. Additionally, you can invoke Push on tags.
Outgoing view To push a range of commits up to a certain commit, select that commit in the Outgoing view and invoke Push Commits from the context menu.

Synchronize

With the Synchronize command, you can push local commits to a remote repository and pull commits from that repository at the same time. This simplifies the common workflow of separately invoking Push and Pull to keep your repository synchronized with the remote repository.

If the Synchronize command is invoked and there are both local and remote commits, the invoked push operation fails. The pull operation on the other hand is performed even in case of failure, so that the commits from the remote repository are available in the tracked branch, ready to be merged or rebased. After the remote changes have been applied to the local branch, you may invoke the Synchronize command again.

In SmartGit's project window, the Synchronize command can be invoked as follows:

from the menu via Remote|Synchronize,
with the Synchronize toolbar button,
and in the Repositories view via Synchronize in the repository's context menu.

Note

Why does SmartGit first Push, then Pull?

SmartGit first tries to Push, then Pulls. If the Push failed because of remote changes, you will have the remote changes already locally available and can test the local changes before pushing them by invoking Push or Synchronize a second time.

If SmartGit would first Pull and then Push, local changes either would be rebased on top of the pulled remote changes or remote changes silently merged to local changes. This would mean to push untested changes.

Viewing the Project History

Log

SmartGit's Log displays the repository's history as a list of commits, sorted by increasing age, and with a graph on the left side to show the parent-child relationships between the commits. What is shown on the Log depends on what was selected when the Log command was invoked:

To view the history of the entire repository (root Log), select the repository in the Repositories view before invoking the Log command.
To view the history of a directory within the repository, select the directory in the Repositories view before invoking the Log command.
To view the history of a single file within the repository, select the file in the Files view before invoking the Log command. If the file is not visible in the Files view, either adjust the file table's filter settings (on its top right), or enter the name of the file in the search field above the file table.

A root Log can be invoked from other places in SmartGit as well:

Branches view In the Branches view (just project window), you can right-click on a branch and select Log to open the Log for the selected branch.
Outgoing view In the Outgoing view, you can right-click on a specific commit and invoke Log to open the Log for the current branch, with the selected commit pre-selected in the Log.

Log Commands

In the Log Frame, many commands which are known from the Project Window are available as well:

most of them are available from the main menu bar
the context menu on a commit provides certain commands
certain items in the Graph view, like local refs or the HEAD-arrow can be modified using drag-and-drop.

Links to issue trackers

If you have set up a so called Bugtraq Configuration, SmartGit will detect issue IDs in commit messages and display links to the issue tracker in this case. The Bugtraq configuration is stored either in the .gitbugtraq file in your repository root (for all users of the repository) or in your repositories' .git/config (just for you). It consists of a named bugtraq section which basically defines a regular expression to match issue IDs in your commit message and an URL template to open when clicking at such an issue link.

Example

An example configuration for the JIRA issue tracker at host 'host' for a project called 'SG' looks like the following.

[bugtraq "jira"] url = https://host/jira/browse/SG-%BUGID% logRegex = SG-(\\d+)

The logRegex must contain only one matching group '()' matching the issue ID. You can use additional non-matching groups '(?:)' for other parts of your regex (or '(?i)' for case insensitive matching). For more details refer to the complete specification at https://github.com/mstrap/bugtraq.

Blame

SmartGit's Blame window displays the history information for a single file in a way that helps you to track down the commit in which a certain portion of code was introduced into the repository. You can open the Blame window by selecting a file in the Files view in SmartGit's project window and invoking Query|Blame from the program menu. The Blame window consists of a Document view and a History of current line view.

Document view

The Document view is divided into three parts: some controls on top, a read-only text view on the right, and an info area on the left. With the controls on top, you can do two things: specify the View Commit at which the text view will display the file contents, and set how to Highlight the lines in the text view:

Change Since The color chosen for a particular line reflects whether the line is 'older' or 'newer' than the specified Commit. More precisely, the color reflects whether the date when the line was last modified lies before or after the date of the commit.
Age The color chosen for a particular line lies somewhere 'between' the two colors used for the oldest and the newest commit in which the file was modified, and thus reflects the line's relative 'age'. You can choose between two age criteria for determining the line color: either Commit Index which refers to the relative position in the relevant commit range (first commit, second commit, etc.) or Time which refers to the commit date, i.e. the point in time at which the commit was created.
Author The color chosen for a particular line depends on the author who made the most recent modification to that line. Each author is mapped to a different color.

The info area shows the commit meta data in a compact format for each line and consists of following columns:

SHA short SHA of the commit
Status will display an '~'-mark if the line has been modified (and not added) and/or an 'M' if the line has been introduced in a merge commit
Author the initials or a short name of the author
Date a compact display of the commit date
Line number the number of the current line

More detailed information for a specific commit will be displayed in the tooltip, when hovering over the info area. The hyperlinks can be used to navigate to the specific commit.

History view

The History of current line view displays the 'history' of the currently selected line from the Document view: the 'history' consists of all detected past and future versions of the line, as it is present in the select View Commit. The position of the currently selected line from the Document view is denoted by pale borders surrounding the corresponding line in the History view.

The detection of a link between a past and a future version of a line depends on the changes which have happened in a commit:

If a certain number of lines has been replaced by exactly the same number of lines within a commit, this change will be detected as modification of the corresponding lines and hence they will share the same history.
If a certain number of lines has been replaced by larger or smaller number of lines, the detection of matching lines depends on the outcome of the internal compare algorithm. For the case where a line has been detected as removed in a commit (instead of replaced by another line, what might be more appropriate), the history contains a leading commit after line has been removed entry to which you can navigate. For the case where a line has been detected as added in a commit (instead of replacing another line, what might be more appropriate), the history contains a trailing commit before line has been added entry to which you can navigate.