FarNet.GitKit 1.3.19

FarNet.GitKit

Far Manager git helpers based on LibGit2Sharp

• About
• Install
• Commands
  • gk:blame
  • gk:branches
  • gk:cd
  • gk:changes
  • gk:checkout
  • gk:clone
  • gk:commit
  • gk:commits
  • gk:config
  • gk:edit
  • gk:init
  • gk:pull
  • gk:push
  • gk:status
• Panels
  • Branches panel
  • Commits panel
  • Changes panel
• Menu
• Settings
• Credentials

---

About

Contents

GitKit is the FarNet module for git operations in Far Manager. GitKit uses LibGit2Sharp and git is not needed as such. Git may be optionally used for getting credentials.

Project FarNet

• Wiki: https://github.com/nightroman/FarNet/wiki
• Site: https://github.com/nightroman/FarNet
• Author: Roman Kuzmin

---

Install

Contents

• Far Manager
• Package FarNet
• Package FarNet.GitKit

How to install and update FarNet and modules
https://github.com/nightroman/FarNet#readme

---

Commands

Contents

GitKit commands start with gk:. Commands are invoked in the command line or using F11 / FarNet / Invoke or defined in the user menu and file associations. Command parameters are key=value pairs separated by semicolons, using the connection string format

gk:command [key=value] [; key=value] ...
gk:@ <command file>

Common parameters

• Repo=<path>

  Specifies the existing repository path.
  Default: the current panel directory.

All commands

• gk:blame
• gk:branches
• gk:cd
• gk:changes
• gk:checkout
• gk:clone
• gk:commit
• gk:commits
• gk:config
• gk:edit
• gk:init
• gk:pull
• gk:push
• gk:status

---

gk:blame

Contents

Shows the specified file line commits in the special editor.

Parameters

• Path=<string>

  Specifies the file to blame. Default: the cursor file.

• IsGitPath=<bool>

  Tells to treat Path as git path.

Keys and actions

• Enter

  Opens the changes panel for the caret line commit.

---

gk:branches

Contents

This command opens Branches panel.

---

gk:cd

Contents

This command navigates to the specified repository item, directory or file.

Parameters

• Path=<string>

  Specifies the path relative to the working tree directory.
  Default: the working tree directory.

  If the path specifies an existing file then the command navigates to its directory panel and sets the cursor to this file.

---

gk:changes

Contents

This command opens Changes panel.

Parameters

• Kind=<enum>

  Specifies the changes kind

  • NotCommitted: includes all not committed changes, i.e. NotStaged and Staged
  • NotStaged: not staged changes (git working directory)
  • Staged: staged changes (git index)
  • Head: last committed changes
  • Last: (default) NotCommitted changes if any, or else Head changes

---

gk:checkout

Contents

This command switches to the specified branch.

Parameters

• Branch=<string>

  The branch name to switch to.
  Default: input dialog.

  If the branch does not exists then it is automatically created from the head branch, with a confirmation dialog.

---

gk:clone

Contents

This command clones the specified repository.

Parameters

• Url=<string> (required)

  Specifies the remote repository.

• Path=<string>

  Specifies the local path to clone into.
  Default: the current panel directory.

• Depth=<int>

  Specifies the cloning depth.
  Default: 0 (full clone).

• IsBare=<bool>

  Tells to clone a bare repository.

• NoCheckout=<bool>

  Tells not to checkout after cloning.

• RecurseSubmodules=<bool>

  Tells to recursively clone submodules.

---

gk:commit

Contents

This command commits changes.

Parameters

• Message=<string>

  The commit message. If it is set then the command commits immediately.

  If the message is empty then the non-modal editor is opened for the message. If CommentaryChar is set then the initial text contains change comments. When the editor closes the command commits.

• All=<bool>

  Tells to stage all changes before committing.

• AllowEmptyCommit=<bool>

  Tells to allow creation of an empty commit.

• AmendPreviousCommit=<bool>

  Tells to amend the previous commit.

• PrettifyMessage=<bool>

  Tells to prettify the message by stripping leading and trailing empty lines, trailing spaces, and collapsing consecutive empty lines. PrettifyMessage is ignored if CommentaryChar is set.

• CommentaryChar=<char>

  The starting line char used to identify commentaries in the commit message. If set (usually to "#"), all lines starting with this char will be removed. CommentaryChar implies PrettifyMessage=true.

Examples

Commit all changes, compose a new message in the editor

gk:commit All=true; CommentaryChar=#

Amend with all changes, modify the old message in the editor

gk:commit All=true; CommentaryChar=#; AmendPreviousCommit=true

---

gk:commits

Contents

This command opens Commits panel.

Parameters

• Path=<string>

  Tells to show commits including the specified file system or git path. Use "?" for the panel cursor file or directory.

  When Path is omitted, the head branch commits are shown.

• IsGitPath=<bool>

  Tells to treat Path as git path.

---

gk:config

Contents

This command shows all config values (global, local) in the special editor.

Keys and actions

• Enter

  Shows the input box for changing the caret line value.

• Ins

  Shows the input box for a new config value.

• Del

  Deletes the caret line config value.

Notes

Git config supports multivalued keys and GitKit shows them in the editor. But changes are limited to single value keys. In other cases edit config files directly.

For example, open the local config directly

gk:edit path=.git/config

---

gk:edit

Contents

This command opens the specified repository file in the editor.

Parameters

• Path=<string>

  Specifies the repository file path relative to the root.
  Default: input dialog.

  Examples

  • README.md - the root README.md
  • .git\config - the local configuration file
  • .git\COMMIT_EDITMSG - the last edited commit message

---

gk:init

Contents

This command creates a new repository.

Parameters

• Path=<string>

  Specifies the new repository directory.
  Default: the current panel directory.

• IsBare=<bool>

  Tells to create a bare repository.

---

gk:pull

Contents

This command pulls the head branch.

---

gk:push

Contents

This command pushes the head branch, with a confirmation dialog.

---

gk:status

Contents

This command prints the repository information like change summary, commit hash, head branch, similar branches, commit message.

Parameters

• ShowFiles=<bool>

  Tells to print changed file statuses and paths before the summary line.

---

Panels

Contents

GitKit provides several panels for browsing and operating

• Branches panel
• Commits panel
• Changes panel

---

Branches panel

Contents

This panel shows the repository branches, local and remote. Branch marks: * head, r remote, = tracked same as remote, < tracked older, > tracked newer, ? tracked orphan.

The panel is opened by the command gk:branches.

Keys and actions

• Enter

  Opens the cursor branch Commits panel.

• ShiftEnter

  Checkouts the cursor branch. For the local branch, makes it the head branch. For the remote branch, creates a new branch from it and makes it the head branch.

• ShiftF5

  Creates a new branch from the cursor branch.

• ShiftF6

  Renames the cursor branch.

• F7

  Creates and checkouts a new branch from the head branch. Note that the head branch is with *, not the cursor. To copy the cursor branch, use ShiftF5.

• F8, Del

  Safely deletes selected local tracking branches.

  Remote, non-tracking, tracking with new commits are not deleted.

• ShiftF8, ShiftDel

  Deletes selected branches including remote, non-tracking, tracking with new commits.

• See also Menu.

---

Commits panel

Contents

This panel shows branch or path commits. Commits are shown by pages of CommitsPageLimit, see Settings.

The panel is opened from the branches panel or by the command gk:commits.

Keys and actions

• Enter

  Opens the cursor commit Changes panel.

• PgDn

  At the last shown commit, loads the next page commits.

• PgUp

  At the first shown commit, loads the previous page commits.

• See also Menu.

---

Changes panel

Contents

This panel shows changed files.

The panel is opened from the commits panel or by the menu "Compare branches" and "Compare commits" or by the command gk:changes.

Keys and actions

• Enter

  Opens the diff tool specified by the setting DiffTool.

• F3, F4

  Opens the diff patch in the viewer or editor.

• AltF4

  If the cursor change file exists, opens this file in the editor.

• See also Menu.

---

Menu

Contents

• Tip info (main menu, branches panel, commits panel)

  Shows the tip or cursor commit info and buttons to copy: SHA-1, Info (shown), Full (full commit message), Short (short commit message).

• Push branch (branches panel, commits panel)

  Branches panel: Pushes the cursor branch, with a confirmation dialog.

  Commits panel: Pushes the commits branch, with a confirmation dialog.

• Merge branch (branches panel)

  Merges the cursor branch into the head branch, with a confirmation dialog.

• Compare branches (branches panel)

  Compares the cursor branch with the selected branch and opens the changes panel. If nothing is selected then the head branch is used.

• Create branch (commits panel)

  Creates a new branch from the cursor commit.

• Compare commits (commits panel)

  Compares the cursor commit with the selected commit and opens the changes panel. If nothing is selected then the tip commit is used.

• Edit file (changes panel)

  If the cursor change file exists, opens this file in the editor.

• Blame file

  Shows the cursor file line commits in the editor, see gk:blame.

• Commit log

  Opens the panel with commits including the cursor file or directory path.

• Help

  Shows GitKit help.

---

Settings

Contents

Settings editor: F11 / FarNet / Settings / GitKit

---

DiffTool and DiffToolArguments

Specify the diff tool and arguments used to compare changed files. In arguments use %1 and %2 as file path substitutes. Environment variables are expanded.

VSCode is used as the default diff tool

%LOCALAPPDATA%\Programs\Microsoft VS Code\bin\code.cmd
--diff "%1" "%2"

File revisions for diff are created in "%TEMP%\FarNet.GitKit". To avoid ceremonies and some known issues, files are not deleted. As a result, files are reused instead of creating again and again.

---

UseGitCredentials

If true, tells to use git credentials for remote tasks. See Credentials for details.
Default: false.

---

CommitsPageLimit

Maximum number of commits per panel pages.
Default: 100.

---

ShaPrefixLength

The number of chars for truncated commit SHA.
Default: 7.

---

Credentials

Contents Settings

Remote git hosts may require credentials, user name and password. GitKit offers two ways, with some advantages and disadvantages.

With UseGitCredentials set to false, an input dialog is used. Enter user name and password and optionally save them for later use. The environment variable GitKit_User is used for keeping credentials.

Alternatively, if you have git installed and available in the path, set UseGitCredentials to true in order to use git for getting credentials.

---