you are reading VERSION = v0.0.16-develop

gitonic simplifies working with multiple git repositories.

gitonic comes with an easy to use Tkinter GUI.

where software components/ artefacts are stored in multiple repositories separately gitonic helps to keep track

Check CHANGELOG for latest ongoing, or upcoming news.

Check BACKLOG for open development tasks and limitations.

IMPORTANT:

gitonic interacts with git just like starting in bash / commandline. at the present time there is no additional error checking. this must be done by checking the log tab manually where all cmdline output goes.

an introduction on how git works in general can be found in the official git documentation in section Git-Basics.

another very good book progit2 can be downloaded from the official github project page. under releases are different formats such as pdf, epub ...

todo - documentation pending

when adding a git repo to the tracked list, and staging files (from different repositories) a following commit command is executed on all repositories in the tracked list with the same commit message. this is not a bug; moreover it is intened to be like that.

following list contains all hotkeys:

HINT:

if not responding to a hotkey, make sure that CapsLock is disabled

the file status is the same as when calling git status --porcelain. see also under git status output.

NOTE: gitonic use porcelain format version 1.

it is possible to configure external formatter tools depending on the file extension.

gitonic will use the configuration file ~/.gitonic/formatter.json.

the general structure is:

{
  ".file-ext": {
    "cmd": "full-path-to-command",
    "para": [
      "%file"
    ]
  }
}

where .file-ext is a simple file extension such as .py, or a comma separated list of extensions .c,.h,.cpp. wild-cards are not supported.

where para is an array of cmd-line options passed to the formatter command where %file is a placeholder and replaced by the file name

for different file extensions gitonic will call the formatter accordingly even if the selected files are of different types (extensions)

all of the following tools are part of gitonic standard installation (available as extra, see below under installation). choose the one what fits best for your needs.

autopep8 is a python formatter what fixes problems reported by pycodestyle. pycodestyle is an official tool from python's code quality authority.

{
  ".py": {
    "cmd": "autopep8",
    "para": [
      "-i",
      "%file"
    ]
  }
}

to use the same code formatter also for cython's files with extension .pyx change the setting to

{
  ".py,.pyx": {
    "cmd": "autopep8",
    "para": [
      "-i",
      "%file"
    ]
  }
}

black is also an offical python tool, but resolves not fully to issues reported by pycodestyle. there might be some rework required (from case to case). result is quite similar to autopep8 beside the list reported by pycodestyle (after formatting) is a bit longer comparing to autopep8 what does a better job here.

{
  ".py": {
    "cmd": "black",
    "para": [
      "%file"
    ]
  }
}

yapf (google python code formmater) is slow comparing the former tools, and re-arranges code so that it is reported as error by pycodestyle after formatting.

{
  ".py": {
    "cmd": "yapf",
    "para": [
      "-i",
      "%file"
    ]
  }
}

all of the following tools are NOT part of gitonic standard installation.

uncrustify is a code formatter for c, c++ (and other languages).

here in this config sample it is configured for extensions .c, .h, and .cpp.

IMPORTANT: uncrustify requires an additional config file, a sample can be found here uncrustify.cfg

here in the sample the uncrustify config file is placed in path ~/.gitonic/uncrustify.cfg. make sure that it is there.

the following needs to be placed inside ~/.gitonic/formatter.json

".c,.h,.cpp": {
    "cmd": "uncrustify",
    "para": [
          "-c",
          "~/.gitonic/uncrustify.cfg",
          "--replace",
          "%file",
          "--no-backup",
          "--if-changed"
    ]
}

when clicking on the changes tab right a context memu opens offering to open the system file manager tool (file explorer) at the base git repo path or at the changed file path.

in addition it is possible to add own custom context menu entries here. configuration is done with ~/.gitonic/context.json file.

the general structure is:

{
  "a-context-name-ctx": {
    "expr": "*",
    "workdir": ".",
    "menu": [
      [
        "some text $GIT",
        [
          "cmd-path",
          "whatever_param=$GIT"
        ]
      ],
      [
        "some other text $PATH",
        [
          "cmd-path2",
          "whatever_param=$PATH"
        ]
      ]
    ]
  },
  ...
}

here the variables $GIT, $PATH, $FILE, or $PYTHON are replaced by the corrosponding path before execution. where $PYTHON expands to sys.executable from gitonic runtime.

the expr key contains a single file pattern, or a list of file patterns - when to enable the context menu. the file pattern is following Unix filename pattern matching.

the workdir key will change the current working directory before running the command.

the menu array contains the text to display in the menu, and the command params as embedded array.

the context name as such can have any value (as long it is unique in the structure).

below a sample ~/.gitonic/context.json file for running on linux with xfce.

{
  "term-ctx": {
    "expr": "*",
    "menu": [
      [
        "Open Terminal at $GIT",
        [
          "xfce4-terminal",
          "--working-directory=$GIT"
        ]
      ],
      [
        "Open Terminal at $PATH",
        [
          "xfce4-terminal",
          "--working-directory=$PATH"
        ]
      ],
      [
        "Edit .gitignore at $GIT",
        [
          "xed",
          "$GIT/.gitignore"
        ]
      ]
    ]
  },
  "spyder-ctx": {
    "expr": "*.py",
    "menu": [
      [
        "spyder python $FILE",
        [
          "~/spyder/.venv/bin/spyder",
          "$FILE"
        ]
      ]
    ]
  },
  "autopep8-ctx": {
    "expr": "*.py",
    "menu": [
      [
        "autopep8 python $FILE",
        [
          "autopep8",
          "-i",
          "$FILE"
        ]
      ]
    ]
  },
  "geany-path": {
    "expr": [
      "*.c",
      "*.cpp",
      "*.h"
    ],
    "menu": [
      [
        "geany c $FILE",
        [
          "geany",
          "$FILE"
        ]
      ]
    ]
  },
  "uncrustify-path": {
    "expr": [
      "*.c",
      "*.cpp",
      "*.h"
    ],
    "menu": [
      [
        "uncrustify c $FILE",
        [
          "uncrustify",
          "-c",
          "~/.gitonic/uncrustify.cfg",
          "--replace",
          "$FILE",
          "--no-backup",
          "--if-changed"
        ]
      ]
    ]
  },
  "git-base-tools": {
    "expr": [
      "*"
    ],
    "workdir" : "$GIT",
    "menu": [
      [
        "gitk $GIT",
        [ 
          "gitk" 
        ]
      ],
      [
        "git gui $GIT",
        [ 
          "git",
          "gui" 
        ]
      ]
    ]
  }
}

remark: the sample config file provides support for opening

• terminal, in this case xfce4-terminal, can be replaced by e.g. xterm - depending on your distribution
• .gitignore file for selected repo with xed
• spyder-ide.org, for files matching *.py
• geany, for files matching *.c, *.cpp, *.h
• gitk and git gui the base git tools which are automatically installed with git

limitation:

at the present time the context menu only works on the underlying file (row) in the table. there is no support for multiple files (selection) as of now.

tested on python3, and linux

alpha state, use on your own risk!!!

it is recommented to install gitonic into a virtual environment. the following script will install gitonic in your home directory (linux).

# create virtual environment 
cd ~
python3 -m venv gitonic

# install gitonic with recommended extras
~/gitonic/bin/pip install gitonic[PEP08,MELD]
or
~/gitonic/bin/pip install gitonic[DEFAULT]

this script can be found here install_linux.sh

to install just gitonic without the extras replace with

# install gitonic 
~/gitonic/bin/pip install gitonic

to run gitonic use the script from the virtual environment directly (no prior venv activation required)

~/gitonic/bin/gitonic

it is recommented to create an alias in .bash_aliases. add the following line at the end of .bash_aliases

alias gitonic=~/gitonic/bin/gitonic

to use git difftool, and mergetool, download and install a 3rd party tool like meld merge and configure like described below.

note:

with gitonic >= v0.12.0 meld is already included in standard installation (as extra, see also under installation) and download is obsolete when installed as part of gitonic. you just need to configure git then.

in case meld installation fails install into the virtual environment

cd ~
~/gitonic/bin/pip install PyGObject

options can be combined by |. use

~/gitonic/bin/pip install gitonic[*options*] 

when during startup an error is thrown, refer to installation on raspberry, fedorra

add a .git-credentials file as described here git-credentials

add a .gitconfig file as described here git-config and configure for diff and merge tools. NOTE: you need to install the diff-tool e.g. meld merge manually, if meld is not installed pressing the button will have no effect.

[user]
    name = your name
    email = [email protected]
    
[credential]
    helper = store

[diff]
    tool = meld
[difftool]
    prompt = false
[difftool "meld"]
    cmd = meld --newtab "$LOCAL" "$REMOTE"

[merge]
    tool = meld
[mergetool "meld"]
    # Choose one of these 2 lines (not both!) 
    # cmd = meld "$LOCAL" "$MERGED" "$REMOTE" --output "$MERGED"
    cmd = meld --newtab "$LOCAL" "$BASE" "$REMOTE" --output "$MERGED"

the following tools are part of the standard git distribution

• gitk git history browser
• git-gui a git front end

other gui-clients are listed on git-scm

following files are used:

HINT: crash after configuration change can be resolved by changing the setting manually in config.json, or delete the config file to fall back to the defaults

gitonic is released under the following LICENSE