[Ranger-users] Visualize version control system information in ranger

[Abdó Roig-Maranges]

Hi,

Recently, Hut merged into ranger's master branch a piece of code I wrote
to display version control system details in ranger's directory
view. This feature is disabled by default, due to non-negligible
overheat with big repos, so Hut suggested I wrote some advertising for
it. Here it goes.


What it does
------------

The patch gathers information of files and directories under version
control, like branch name, commit message, state of file, etc and
displays it in ranger's interface.

For directories which are at the root of the vcs, it displays two
characters next to the directory name. the first tells about the local
status of the working dir (√ clean, * modified files, + new files), the
second character informs about the state regarding a tracking repo (<
behind, > ahead, = in sync, Y diverged)

Inside a repo, every file has a character which tells about the state of
that file with respect to the last commit (√ unchanged, * modified, +
new, - deleted, · ignored)

Finally, it also displays, in the status line, the branch name and last
commit message for the repo in the current directory.

In addition to this, there are some ranger commands to interact with the
version control. Currently, to display logs and diffs, and to add /
remove files from the index.


Why use it
-----------

With this feature enabled, you can see which projects have pending
commits, need to be pushed, or which files have changed and how,
directly from ranger. For me, it is much much more efficient seeing this
data effortlessly in ranger, than constantly opening shells and
performing 'git status'. Of course, at the end it is a matter of your
particular workflow.


Config settings
---------------

The configuration settings, which can be adjusted in rc.conf, are the
following:

  set vcs_aware true           # enable / disable the vcs feature

  set vcs_backend_git enabled  # enable / disable the git backend
  set vcs_backend_hg  local    # enable / disable the mercurial backend
  set vcs_backend_bzr local    # enable / disable the bazaar backend

The 'vcs_backend_xxx' variables, set the state for individual
backends. the possible values are:

  disabled:  don't collect any information.
  local:     collect and display only information available locally.
  enabled:   collect and display local and remote data.

The distinction between 'local' and 'enabled' is because some of the vcs
(hg, bzr) need network access to get the state of the remote (tracking)
repo. For those, 'local' does not gather remote data, speeding up things
considerably. For git, there is no difference between 'enabled' and
'local', as everything we display is available locally.


Commands
--------

Currently there are 4 commands available involving the vcs:

  stage:    add the selection to the vcs index (i.e. git add)
  unstage:  remove the selection from the git index (i.e. git reset)
  diff:     display a diff for the selected files
  log:      display the log for the selected files

These are the ones I found more useful for my particular workflow,
otherwise I prefer opening a shell and using the command line. But of
course, there is a lot of room for anyone interested writing their own
commands adapted to their needs.


Extending it
------------

I wrote this mainly to satisfy my needs. This means I focused on git,
and added hg and bzr as a bonus, because I already had most of the
backend code written for other reasons. It is designed so it can be
easily extended from two ends:

1) Adding new backends. The code abstracting the access to the vcs is in
   ranger/ext/vcs. To create a new backend, you may want to start from
   ranger/ext/vcs/git.py, for instance.

   The external abstracted interface to the vcs is in
   ranger/ext/vcs/vcs.py. The workings of this are more or less
   documented in the docstrings.

   
2) Adding new commands. See ranger/config/commands.py for the code of
   the commands mentioned above. The interaction with the vcs is done
   via an object of class Vcs, which abstracts the interface to the
   different version control backends.

   
Well, that's it. I hope you find this useful!

Abdó Roig-Maranges