GNOME Commander

A powerful file manager for the GNOME desktop environment

Development

This page contains information about hacking and contributing to the GNOME Commander project. We encourage anyone to contribute with code, translations, bugreporting, new useful ideas, or just give some quality feedback that also is quite important.

If you would like to get involved and don't know where to start, have a look especially into the TODO file. This file gives a hint on what we are working on, or like to work on, and maybe appreciate some community efforts on. You are also welcome to sign up on our mailing lists and take part in discussions and development. If you are keen on fixing open bugs, have a look at our gitlab project page.

Current plans

The team behind GCMD is currently working on switching from obsolete libraries, e.g. from gnome-vfs to gvfs/GIO. This is a major task and, thus, will take some time.

Future plans

In the future, the team behind GCMD are will further enhance python plugin support. Plugins should be dropped in the ~/.gnome-commander/plugins directory. The work on supporting meta-data also continues. The plan is to add this functionality to the searchtool, custom columns and the internal viewer.

Git Repository

The official Git repository of GNOME Commander is registered on gitlab.gnome.org.

Branches and Versions

GNOME Commander is being developed in several branches:

• The master branch, where all the normal development takes place. It should always contain a runable version of GCMD.
• One or more stable branches, named after the current stable release (e.g. gcmd-1-6), which only includes bugfixes, doc updates, translation updates, but no new features;
• Optionally, some feature branches, where new ideas or big features are cooked until they are ready to be merged in the master branch.

The version numbers (major, minor and micro) follow the standard of odd and even versioning. Even numbers are stable versions, that are intended for all-day use. Odd versions are development versions. The version number is stored as git-tags in the git repository. To see all of them, just type git tag. The current one is also stored in the first line of configure.ac.

To check out the GCMD repository to your local hard disc, enter the following commands:

The master branch for development (might be instable):
git clone https://gitlab.gnome.org/GNOME/gnome-commander.git

The current stable branch:
git clone -b gcmd-1-16 https://gitlab.gnome.org/GNOME/gnome-commander.git

If you already cloned the repository, run git pull inside the gnome-commander directory to get the latest code revision. To switch between the branches, run git checkout $BRANCH.

Tips for working with Git

• Why not automating meson compile and meson test before every commit? Nothing easier than that: Just type the following command when you are in the top directory of the GCMD repository:
  ln -s ../../pre-commit.sh .git/hooks/pre-commit
  Now, all your commits are automatically tested before they are actually committed via git commit. When you only have a small commit to be made, where no check is necessary, you can avoid it with the command git commit --no-verify.

Building from source

First, check out the source code as described in the previous section. The next step is meson setup builddir && meson compile -C builddir && meson install -C builddir, which should work like a charm.

When you compile Gnome Commander the first time and you discover some dependency errors, install those dependency libraries through your Linux distribution.

Contributing by Developing

If you want to contribute, send in patches, having some useful idea or just some feedback then you are welcome to contact us or you can make a pull request on GitLab against the GCMD repository.

Here is a quick guide how to do contribute via GitLab after creating an account there and creating a fork of the origin repository in GitLab:

1. git clone https://gitlab.gnome.org/$USER/gnome-commander && cd gnome-commander
2. Next, add the original repo to your repo as a reference: git remote add upstream https://gitlab.gnome.org/GNOME/gnome-commander.git
3. Create a branch where you track your work: git checkout -b $BRANCH_NAME
4. Now create one or more commits that contain your work via git commit -m "$DESCRIPTION"
5. If your work is for an already openend issue, say #26, on GitLab, the last commit should contain something like: git commit -m "...; Closes: #26".
6. To be on the safe side, do an update with the original repo, just to make sure that no conflicts have been created in the meantime:git fetch upstream master && git rebase upstream/master
7. Push your changes to your fork on GitLab: git push origin HEAD
8. You can create a merge request: Either by using the link that is shown to you on the terminal after the last command, or by clicking on the "Create merge request" button in the GitLab web interface in your repository from the branch you created above.
9. The maintainer of the original repository will then be notified by GitLab via email and can review, comment, and review, ask for changes and finally accept the merge request. Then your change will be copied to the original repository.

If you want to submit a patch via email:

• Send an email with the patch to the developers or the developer list.
• Please use the following command to generate the patch:diff -Naur old_file new_file
• Include it as text together with a good explanation of what the patch does or what problem/bug it solves.
• You can also do all of that directly via git using git format-patch and git send-email.

Contributing by Translating

The current status of all project translations can be found at GNOME's Damned Lies. For adding a new translation simply download the initial potfile of the master branch and start translating by renaming the file to LL.po (replace "LL" with your language code, see the complete list of language codes). Or take an already existing po file from the list on the page given above.

Here you will find the recipe on how to contribute with your new or updated translation:

1. Get a fresh copy of the program source (either from Git or snapshot)
2. Unpack it and run meson setup builddir for some basic checks.
3. Update proper LL.po file: go into the po directory and run intltool-update LL.

You may find translation compedia to be quite handy as a reference. You can download some po files from other projects and create such a compedium by: msgcat -o compendium-LL.po *.po.

There are several translation tools available. Some of them are: Poedit and Gtranslator.

Have a look at l10n.gnome.org if you want to start translating for more projects than just GCMD.

From time to time check strings marked for translation. Therefore, create updated po/gnome-commander.pot with make check. Then search for incorrect translations:
podebug --format='[i18n]' --input po/de.po > output.po.
Now in the output file all found strings for translation are marked with a [i18n] tag. Then you have to start GCMD with this created po-file.

Making a release

• After version 1.14.0 we will provide release information only in the AppData file. When preparing the release, validate the file through appstream-util validate data/org.gnome.gnome-commander.appdata.xml.in.
• Take note of https://handbook.gnome.org/maintainers/making-a-release.html on the release day
• When creating a new stable branch, inform the translators through a new issue in Damned Lies like here (if there is no other official way until then).

Testing/Creating a Gentoo ebuild

• Create a local overlay via layman wiki.gentoo.org/wiki/Ebuild_repository#Layman
• After successful meson dist -C builddir move the ebuild file from builddir/data/ to /usr/local/portage/gnome-extra/gnome-commander/
cd /usr/local/portage/gnome-extra/gnome-commander
  check ebuild and create manifest: pkgdev manifest
  Perform eix-update if needed.
• Install with emerge and possibly still test for the correct use of the USE flags.
• Look for git pull request policy at gentoo.org/glep/glep-0066.html
• Use pkgcheck to test the new ebuild for errors or style issues from inside the folder where the new Manifest is located in the local gentoo repository: pkgcheck scan gnome-commander-1.16.0.ebuild and finally pkgcheck commit to prepare a commit to your repo.
• Create a fork of the Gentoo repo from github.com/gentoo/gentoo, clone your fork, add the new Manifest line and the ebuild file from the second point above into gnome-extra/gnome-commander/ and create a commit with signing off by doing (git add -p && pkgdev commit), similar to this one.
• Push your commit to your repository at github and create a merge request to Gentoo's repository.

Hacking documents

• Internal-Viewer Internals. This document describes details of the 'intviewer' library, which implements GNOME Commander's Internal-Viewer. If you plan to hack the internal viewer, add features or just browse the source for fun, we recommend reading this document first (However, note that the internal viewer source files in Git are always more updated than this document).

---

Updating the Homepage

If you want to contribute to the Gnome Commander homepage you can simply fork its source code repository and create a pull request with your updates.

The page itself consists of simple html pages like the index.html or doc.html. But you will also notice that the blog posts which are shown on the index.html file are actually markdown posts in the "_posts" subdirectory. When pushing new blog posts in that folder, they are automatically processed by the Jekyll tool on GitHub. No manuall work has to be done in that case. Just create a new markdown file, create a merge request, and when it is accepted, the new post will show up quickly on the Gnome Commander homepage.

Before opening a pull request you may test the look of a new blog post by installing Jekyll locally on your machine and running "jekyll serve" in the main folder of the homepage repository. That will start a local webserver and you can visit the homepage in your browser on page http://localhost:4000.

---

To top of page