Using the Projects Plugin in Kate

Update (2014-10-18): Auto-Loading Projects in Kate 5

Introducing the Projects Plugin for KDE SC 4.10

The basic idea of the Projects plugin is to have a structured list of files belonging to the  project with the following properties:

  1. provide a structured view of the files
  2. make it easy and very fast to open and switch projects
  3. support search & replace for a project
  4. provide simple auto completion
  5. make it simple to quickly open files in the project
  6. support for building the project

We’re going to address all these points now.

1. Provide a Structured View of the Files

Once the “Projects Plugin” is loaded in the Kate config page, a sidebar appears that lists all projects as well as the projects files as follows:

As you can see, the currently active project is “Kate”, and it’s contents is listed in the tree view. Clicking on files in the tree view opens the file in the editor. Further, a context menu is provided with which you can open files with other applications, such as a .ui file with Qt Designer.

2. Switching Projects

The idea is that you never have to open a project manually, this is even not supported at all. Hence, what happens if you open a file, the Project Plugin quickly scans the folder and its parent folders for a .kateproject file. If found, the project is automatically loaded. Very simple and efficient.

Further, if you open another document in Kate, that belongs to another project, the Project plugin automatically switches the current project. So intuitively, always the correct project is active. Of course, you can also switch the currently active project through the combo box.

3. Search & Replace in Projects

Kate has a “Search & Replace” plugin that shows up in the bottom sidebar. If a project is loaded and you open the “Search & Replace” sidebar, it automatically switches to the mode to search & replace in the current project, which usually is exactly what you want:

4. Simple Auto Completion

With the knowledge of all files belonging to a project, the Project plugin provides simple auto completion facilities based on ctags. If a project is initially opened, ctags parses all project files in a background thread and saves the ctags information to /tmp. This file then is used to populate the auto completion popup in Kate. In contrast, without this auto completion, Kate was only capable of showing auto completion items based on the words in the current file. So the auto completion provided by the Project plugin is much more powerful.

If ctags is missing, a passive popup warns you about this. It is also noteworthy, that the ctags file in /tmp is cleaned up when Kate exists, so you the plugin does not pollute any folder with unwanted files.

5. Quick Opening Files

As clicking on files in the tree view is not the fastest way to open a file, Kate provides a built-in quick open mechanism you can activate with CTRL+ALT+o. What you the get is a list like this:

You can filter by typing parts of the file name you are looking for, and you can also navigate with the arrow keys and page up/down through the list. Hitting enter activates the selected file, while escape hides the quick open view again.

Further, the quick open remembers the previous file. So when you change to the quick open view the previously activated  file is automatically selected and you just need to hit enter, which comes very handy at times.

6. Support for Building the Project

Another feature is to have support in the Build plugin, so that it automatically is configured correctly.

Creating Projects

Currently, creating a project requires some manual work, although it is really not much. You just have to create a .kateproject file in the root folder of the project. For instance, the Kate .kateproject file looks like this:

  "name": "Kate"
, "files": [ { "git": 1 } ]

As you may have noted, this is JSON syntax (because there is a nice jason library for Qt to parse this). The project name is “Kate”, and the files contained in should be read from git.

What’s also supported instead of “git” is subversion through “svn” and mercurial through “hg” (btw, it would be nice to have support for other version control systems as well *hint*). If you do not want to read from a version control system, you can tell it to recursively load files from directories as follows:

  "name": "Kate"
, "files": [ { "directory": "kate", "filters": ["*.cpp", "*.h", "*.ui", "CMakeLists.txt", "Find*.cmake"], "recursive": 1 } ]

Here, subfolders and filters define what’s part of the project. You can also mix version control and files based on filters.

If you want to add support for the Build plugin, you could write a .kateconfig like this:

  "name": "Kate"
, "files": [ { "git": 1 } ]
, "build": {
    "directory": "build"
  , "build": "make all"
  , "clean": "make clean"
  , "install": "make install"

Hopefully, these examples help you to setup your own project.


Kudos go to Christoph, he implemented all the features in here. The Project plugin will be shipped with  KDE SC 4.10, and you should really try it out :-)

33 thoughts on “Using the Projects Plugin in Kate

    1. What do you mean by that? Once a .kateproject file is created, you have a simple project management and a lightweight text editor. Kate cannot be compared to KDevelop. If you want KDevelop features, use KDevelop :)

  1. Per-project coding style support would be a killer feature for Kate. It’s now very tedious to edit multiple projects at once when they have different coding styles.

    1. We already have solutions to this: Use modelines (=document variables), then you always get exactly what you want… That simple:
      Besides that, you can also use a .kateconfig file, which maybe also would solve your issue…

      Besides, this plugin is a Kate application plugin, while all the configuration comes from the Editor Part. Hence, both parts are completely separated for a technical reason. Thus, you have this editor part also in KDevelop, Kile and other applications.

  2. Thanks guys, this was a very sought after feature in Kate by me recently when editing the material files for a game and some quick source modifications, feels nice you can read minds! :D

  3. Looks great, I need it !! Maybe out of the scope of the project plugin but one thing I’d really love to have when I manage a project with a lot of opened files is something like the current tabbar plugin, but it should only show a tab for opened file tagged as “favorite” (with a shortcut or something like that). With this, you can quickly go to files that you often use and don’t bother to clean up your opened files all the time

  4. So, now that Kate is getting close in functionality, will KWrite get closer to the good-old Kate? Just kiding ;)

    You are doing and amazing job!!!

  5. This plugin is great, exactly what I missed from kate.

    But, some questions arise:

    Are sessions and projects meant to work together or fulfil they a different need?
    I currently use the build and gdb plugin, where I require (especially for gdb) multiple targets. Will I be able to configure this in the future in the project plugin or will they remain separated?

    1. Projects are for a different need: Quick file access and fast switching.
      Sessions: specific plugin configuration (including the Projects plugin), remember open documents and other configuration.

      With respect to the gdb-plugin: please open a bug report, then Kåre will read it.

        1. There are several isLocalFile() queries in the Projects plugin source code, so I guess it only works for local projects. I may be wrong, though. Why don’t you just try it?

          1. I stumbled upon this as I was trying to figure this out for myself. It definitely does NOT work via sftp:// which is unfortunate – it would be very useful. All of my dev work is stored on a remote VPS, so I’m unable to use the project plugin. I suspect that it would be pretty slow, anyways. Oh well, I’ll probably come up with some way to integrate this into my workflow.

  6. How do you set filters for current directory?
    “files”: [ { “directory”: “.”, “filters”: [(…)
    does not work

    1. This just did work for me:
      "name": "Test"
      , "files": [ { "directory": ".", "filters": ["*.html"], "recursive": 1 } ]

      Are you sure you don’t have a syntax error? Is the project listed in the Projects tab?

      1. Thank you this worked for me. I have the directory name and I changed to “.” and now workds. My sample file

          "name": "Soccer Template"
        , "files": [ { "directory": ".",
              "filters": [
            "recursive": 1 } 
  7. Great plugin!

    However, I failed to figure out, how to define multiple projects in .kateproject. I would like to have the following two projects but whatever syntax I try, it does not work.

    I am just curions to know. This is no real problem, because the two ‘projects’ are in different subdirectories with their own .kateproject-file.

      "name": "web-code"
      , "files": [ { "directory": "local-web-home", "filters": ["*.xsl", "*.css", "*.cmd"], "recursive": 1 } ]
      "name": "web-content"
      , "files": [ { "directory": "local-web-home", "filters": ["*.xml", "*.html"], "recursive": 1 } ]
    1. Thanks for asking this. Turns out, the answer was in the source code. There you go:

        "name": "Web Project",
        "projects": [
            "name": "Styling"
            , "files": [ { "directory": "local-web-home", "filters": ["*.xsl", "*.css", "*.cmd"], "recursive": 1 } ]
            "name": "Contents"
            , "files": [ { "directory": "local-web-home", "filters": ["*.xml", "*.html"], "recursive": 1 } ]
  8. I’ve tried everything listed here. Kate will not list my project in the drop down & the “Open Projects” menu item is gone on recent builds. Can we get the manual open back please?

    1. Make sure the filename is “.kateproject” and not “bla.kateproject”.
      And then, just open a file in the respective (sub)-directory. The project will then automatically be opened.

      1. I’m having difficulty getting this to work. Using kate 4.11, my .kateproject is listed below.

        “name”: “Game Server”,
        “files”: [ { “filters”: [ “*.cpp”, “*.h”] } ]

        “build”: {
        “directory”: “build”
        , “build”: “make all”
        , “clean”: “make clean”

        this .kateproject doesn’t work, commandline error says “json_parser – syntax error found, forcing abort, Line 1 Column 0 ”
        However, if I change the file to:

        “name”: “Game Server”,
        “files”: [ { “filters”: [ “*.cpp”, “*.h”] } ]

        It works perfectly. Any idea?

  9. Hello, I would like to add some hidden files in my project but
    “filters”: [“.htaccess”] does not work. How can I do this?

  10. I think there is a bug.

    When manually specifying files to included, everything is fine. But when using “git” mode, files with non-ASCII file names (for example, Chinese characters) will not appear in the project sidebar, even if they are actually included in the git repository.

    I’m using Kate 3.14.

  11. This is great. I have a few issues, though.

    Apparently files are not being reload in the project file list. If i create new files, they do not appear under the files list and i can’t open them through the quick file open dialog. The refresh button is not working.

    Hope this gets fixed.

  12. Just ran a dnf update (kate version is now 15.08.1) and its broken. I just see and no other files. Was one of my favorite features.

Leave a Reply

Your email address will not be published. Required fields are marked *

Scroll to top