Merge lp:~mhr3/libunity/remove-scopes-via-dconf into lp:libunity

[Michal Hruby]

Refactor scope discovery to allow easy OEM customization - removal and locking of scopes via dconf.

Refactor scope discovery to allow easy OEM customization - removal and locking of scopes via dconf.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:290
http://jenkins.qa.ubuntu.com/job/libunity-ci/110/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-amd64-ci/95
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-armhf-ci/95
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-i386-ci/95

Click here to trigger a rebuild:
http://s-jenkins:8080/job/libunity-ci/110/rebuild

review: Approve (continuous-integration)

[lp:~mhr3/libunity/remove-scopes-via-dconf]

291. By Michal Hruby on 2013-09-03

Add a test for the XDG branch of find_scopes

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:291
http://jenkins.qa.ubuntu.com/job/libunity-ci/111/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-amd64-ci/96
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-armhf-ci/96
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-i386-ci/96

Click here to trigger a rebuild:
http://s-jenkins:8080/job/libunity-ci/111/rebuild

review: Approve (continuous-integration)

[lp:~mhr3/libunity/remove-scopes-via-dconf]

292. By Michal Hruby on 2013-09-03

Add tests for hidden scopes

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:292
http://jenkins.qa.ubuntu.com/job/libunity-ci/112/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-amd64-ci/97
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-armhf-ci/97
    FAILURE: http://jenkins.qa.ubuntu.com/job/libunity-saucy-i386-ci/97/console

Click here to trigger a rebuild:
http://s-jenkins:8080/job/libunity-ci/112/rebuild

review: Needs Fixing (continuous-integration)

[lp:~mhr3/libunity/remove-scopes-via-dconf]

293. By Michal Hruby on 2013-09-04

Bump changelog

294. By Michal Hruby on 2013-09-04

Skip non existing directories without throwing an error

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:294
http://jenkins.qa.ubuntu.com/job/libunity-ci/113/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-amd64-ci/98
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-armhf-ci/98
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-i386-ci/98

Click here to trigger a rebuild:
http://s-jenkins:8080/job/libunity-ci/113/rebuild

review: Approve (continuous-integration)

[lp:~mhr3/libunity/remove-scopes-via-dconf]

295. By Michal Hruby on 2013-09-06

Finish up merging from multiple locations

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:295
http://jenkins.qa.ubuntu.com/job/libunity-ci/114/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-amd64-ci/99
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-armhf-ci/99
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-i386-ci/99

Click here to trigger a rebuild:
http://s-jenkins:8080/job/libunity-ci/114/rebuild

review: Approve (continuous-integration)

[Paweł Stołowski (stolowski)]

27 + <key type="as" name="locked-scopes">
Why is this part of this MP?

100 + var overriden_dirs = Environment.get_variable ("LIBUNITY_SCOPE_DIRECTORIES");
I think just SCOPE_DIRECTORIES would be fine?

169 + if (scope_id in hidden_scope_ids)
170 + throw new ParseError.FILE_NOT_FOUND ("Scope not found: %s", scope_id);

196 + if (data.id in hidden_scope_ids)
197 + throw new ParseError.FILE_NOT_FOUND ("Scope not found: %s", data.id);

I think we shouldn't be hiding the real cause and instead extend ParseError domain with SCOPE_HIDDEN or so.

265 + yield build_scope_node_tree (root_node, scope_dir);
In theory build_scope_node_tree may throw (in practice it won't for directories unless I overlooked something), so can you try-catch here just to be on the safe side (we should never break this loop even if single directory fails)?

439 + if (child_node.data.get_overrides_subscopes () &&
440 + child_node.n_children () == 0)
...
462 + else
Can you add some debug statements around both cases?

I think that the docstring of find_scopes_for_id needs to be updated?

review: Needs Fixing

[lp:~mhr3/libunity/remove-scopes-via-dconf]

296. By Michal Hruby on 2013-09-06

Fixes based on review comments

[Michal Hruby (mhr3)]

> 27 + <key type="as" name="locked-scopes">
> Why is this part of this MP?

Both removing scopes via dconf and locking them are features for OEMs.

> 100 + var overriden_dirs = Environment.get_variable
> ("LIBUNITY_SCOPE_DIRECTORIES");
> I think just SCOPE_DIRECTORIES would be fine?

I think it's good to have namespaced envvars, it's also consistent with the other envvars (LIBUNITY_TIME_SEARCHES etc.)

> 169 + if (scope_id in hidden_scope_ids)
> 170 + throw new ParseError.FILE_NOT_FOUND ("Scope not found: %s",
> scope_id);
>
> 196 + if (data.id in hidden_scope_ids)
> 197 + throw new ParseError.FILE_NOT_FOUND ("Scope not found: %s",
> data.id);
>
> I think we shouldn't be hiding the real cause and instead extend ParseError
> domain with SCOPE_HIDDEN or so.

I actually wanted to keep it the same, cause a hidden scope should behave exactly the same as if it weren't installed, we wouldn't want to see "... catch (ParseError.HIDDEN_SCOPE) { ... // haha, you're lying! I'll do something about it }"

> 265 + yield build_scope_node_tree (root_node, scope_dir);
> In theory build_scope_node_tree may throw (in practice it won't for
> directories unless I overlooked something), so can you try-catch here just to
> be on the safe side (we should never break this loop even if single directory
> fails)?
>
> 439 + if (child_node.data.get_overrides_subscopes () &&
> 440 + child_node.n_children () == 0)
> ...
> 462 + else
> Can you add some debug statements around both cases?

Added for the if, the else recurses, so it's logged already.

> I think that the docstring of find_scopes_for_id needs to be updated?

Not really, still applies.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:296
http://jenkins.qa.ubuntu.com/job/libunity-ci/115/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-amd64-ci/100
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-armhf-ci/100
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-i386-ci/100

Click here to trigger a rebuild:
http://s-jenkins:8080/job/libunity-ci/115/rebuild

review: Approve (continuous-integration)

[Paweł Stołowski (stolowski)]

> > 27 + <key type="as" name="locked-scopes">
> > Why is this part of this MP?
>
> Both removing scopes via dconf and locking them are features for OEMs.
Ok, please update commit message then ;).

> I actually wanted to keep it the same, cause a hidden scope should behave
> exactly the same as if it weren't installed, we wouldn't want to see "...
> catch (ParseError.HIDDEN_SCOPE) { ... // haha, you're lying! I'll do something
> about it }"
How about changing error message then? That will be useful when looking at logs.

review: Needs Fixing

[Michal Hruby (mhr3)]

> Ok, please update commit message then ;).

Updated.

> How about changing error message then? That will be useful when looking at
> logs.

That still makes the special casing possible.

[lp:~mhr3/libunity/remove-scopes-via-dconf]

297. By Michal Hruby on 2013-09-06

Change error message

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:297
http://jenkins.qa.ubuntu.com/job/libunity-ci/116/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-amd64-ci/101
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-armhf-ci/101
    SUCCESS: http://jenkins.qa.ubuntu.com/job/libunity-saucy-i386-ci/101

Click here to trigger a rebuild:
http://s-jenkins:8080/job/libunity-ci/116/rebuild

review: Approve (continuous-integration)

[Paweł Stołowski (stolowski)]

Looks good, thanks!

review: Approve

=== modified file 'configure.ac'
--- configure.ac	2013-08-27 14:20:54 +0000
+++ configure.ac	2013-09-06 15:44:22 +0000
@@ -1,5 +1,5 @@
 # When releasing also remember to update the soname as instructed below
-AC_INIT(libunity, 7.1.0)
+AC_INIT(libunity, 7.1.1)
 
 AM_INIT_AUTOMAKE(AC_PACKAGE_NAME, AC_PACKAGE_VERSION)
 AM_CONFIG_HEADER(config.h)

=== modified file 'data/com.canonical.Unity.Lenses.gschema.xml.in.in'
--- data/com.canonical.Unity.Lenses.gschema.xml.in.in	2013-05-08 15:11:34 +0000
+++ data/com.canonical.Unity.Lenses.gschema.xml.in.in	2013-09-06 15:44:22 +0000
@@ -14,7 +14,17 @@
     <key type="as" name="disabled-scopes">
       <default>[]</default>
       <summary>Scopes that will be ignored during queries.</summary>
-      <description>List of scope IDs that will be ignored when master scopes are querying their subscopes.</description>
+      <description>List of scope IDs that will be ignored when master scopes are querying their subscopes (this list changes when user enables or disables a scope).</description>
+    </key>
+    <key type="as" name="hidden-scopes">
+      <default>[]</default>
+      <summary>Scopes that are blacklisted.</summary>
+      <description>List of scope IDs that will be considered the same as if they were not installed at all.</description>
+    </key>
+    <key type="as" name="locked-scopes">
+      <default>[]</default>
+      <summary>Scopes that cannot be enabled nor disabled by the user.</summary>
+      <description>List of scope IDs that the user will see as installed and won't be able to enable nor disable.</description>
     </key>
     <key type="as" name="home-lens-priority">
       <default>['files.scope', 'music.scope' ]</default>

=== modified file 'debian/changelog'
--- debian/changelog	2013-08-28 13:23:31 +0000
+++ debian/changelog	2013-09-06 15:44:22 +0000
@@ -1,3 +1,9 @@
+libunity (7.1.1-0ubuntu1) UNRELEASED; urgency=low
+
+  * Allow permanent scope "removal" just by using dconf.
+
+ -- Michal Hruby <[e-mail]>  Wed, 04 Sep 2013 10:05:06 +0100
+
 libunity (7.1.0+13.10.20130828.1-0ubuntu1) saucy; urgency=low
 
   [ Pawel Stolowski ]

=== modified file 'protocol/protocol-scope-discovery.vala'
--- protocol/protocol-scope-discovery.vala	2013-08-06 08:09:15 +0000
+++ protocol/protocol-scope-discovery.vala	2013-09-06 15:44:22 +0000
@@ -189,7 +189,10 @@
     private static const string SCOPE_GROUP = "Scope";
     private static const string DESKTOP_GROUP = "Desktop Entry";
 
+    private static string[] scope_directories = null;
     private static string[] scope_file_prefixes = null;
+    private static bool overrides_scope_dirs = false;
+
     private static string extract_scope_id (string path)
     {
       string? real_path = null;
@@ -200,17 +203,7 @@
         path = real_path;
       }
 
-      if (scope_file_prefixes == null)
-      {
-        foreach (unowned string data_dir in Environment.get_system_data_dirs ())
-        {
-          var sys_path = Path.build_path (Path.DIR_SEPARATOR_S,
-                                          data_dir, SCOPES_DIR, null);
-          var f = File.new_for_path (sys_path);
-          // this will resolve relative paths
-          scope_file_prefixes += "%s/".printf (f.get_path ());
-        }
-      }
+      if (scope_file_prefixes == null) init_scope_file_prefixes ();
 
       string normalized_path = path.replace ("//", "/");
 
@@ -230,9 +223,54 @@
       return Path.get_basename (path);
     }
 
+    internal static void init_scope_file_prefixes ()
+    {
+      if (scope_directories == null) init_scope_directories ();
+      scope_file_prefixes = {};
+      foreach (unowned string scope_dir in scope_directories)
+      {
+        var f = File.new_for_path (scope_dir);
+        // this will resolve relative paths
+        scope_file_prefixes += "%s/".printf (f.get_path ());
+      }
+    }
+
+    internal static void init_scope_directories ()
+    {
+      var overriden_dirs = Environment.get_variable ("LIBUNITY_SCOPE_DIRECTORIES");
+      overrides_scope_dirs = overriden_dirs != null;
+      if (overriden_dirs == null)
+      {
+        scope_directories = {};
+        var data_dirs = Environment.get_system_data_dirs ();
+        foreach (unowned string data_dir in data_dirs)
+        {
+          scope_directories += Path.build_filename (data_dir, SCOPES_DIR);
+        }
+      }
+      else
+      {
+        scope_directories = overriden_dirs.split (":");
+      }
+    }
+
 
     public class ScopeMetadata
     {
+      private static string[] hidden_scope_ids;
+      static construct
+      {
+        // the hidden scopes are not supposed to be changed, so no need
+        // to monitor for dynamic changes
+        update_hidden_scope_ids ();
+      }
+
+      internal static void update_hidden_scope_ids ()
+      {
+        var settings = new Settings ("com.canonical.Unity.Lenses");
+        hidden_scope_ids = settings.get_strv ("hidden-scopes");
+      }
+
       /* careful here, although it's a private lib, keeping it
        * ABI compatible is a good idea (unity-core uses it) */
       public string id;
@@ -265,6 +303,7 @@
       private CategoryDefinition[] categories;
       private FilterDefinition[] filters;
       private string[] subscope_ids;
+      private bool overrides_subscopes;
 
       public unowned CategoryDefinition[] get_categories ()
       {
@@ -280,6 +319,11 @@
         return subscope_ids;
       }
 
+      internal bool get_overrides_subscopes ()
+      {
+        return overrides_subscopes;
+      }
+
       public void load_from_key_file (KeyFile file) throws Error
       {
         this.domain = null;
@@ -403,6 +447,7 @@
         if (file.has_key (SCOPE_GROUP, "Subscopes"))
         {
           this.subscope_ids = file.get_string_list (SCOPE_GROUP, "Subscopes");
+          this.overrides_subscopes = true;
         }
 
         const string FILTER_PREFIX = "Filter ";
@@ -505,11 +550,23 @@
       {
         debug ("for_id: %s", scope_id);
 
+        if (scope_id in hidden_scope_ids)
+          throw new ParseError.FILE_NOT_FOUND ("Scope is disabled: %s", scope_id);
+
         string full_path;
         var file = new KeyFile ();
-        var path = "%s/%s".printf (SCOPES_DIR, scope_id);
-        bool loaded = file.load_from_data_dirs (path, out full_path,
-                                                KeyFileFlags.NONE);
+        bool loaded;
+        if (overrides_scope_dirs)
+        {
+          loaded = file.load_from_dirs (scope_id, scope_directories,
+                                        out full_path, KeyFileFlags.NONE);
+        }
+        else
+        {
+          var path = "%s/%s".printf (SCOPES_DIR, scope_id);
+          loaded = file.load_from_data_dirs (path, out full_path,
+                                             KeyFileFlags.NONE);
+        }
 
         if (!loaded)
           throw new ParseError.FILE_NOT_FOUND ("Scope not found: %s", scope_id);
@@ -546,6 +603,9 @@
         data.full_path = full_path;
         data.id = extract_scope_id (full_path);
 
+        if (data.id in hidden_scope_ids)
+          throw new ParseError.FILE_NOT_FOUND ("Scope is disabled: %s", data.id);
+
         return data;
       }
     }
@@ -568,123 +628,74 @@
     {
     }
 
+    static construct
+    {
+      init_scope_directories ();
+    }
+
     /**
-     * Process .scope file and scopes in a subdirectory if it's master scope.
+     * Build registry of all scopes in start_path.
+     * start_path can be a directory, a .scope file path or just scope id (.scope file name, including extenstion).
      *
-     * @param filename path of a .scope file
+     * @param start_path starting directory or specific .scope file
+     * @return registry of all scopes (if start_path is a dir) or just one scope and its subscopes.
      */
-    private async void process_scope (string filename) throws Error
+    public static async ScopeRegistry find_scopes (string? start_path) throws Error
     {
-      debug ("process_scope: %s", filename);
-
-      ScopeMetadata scope_data = ScopeMetadata.for_path (filename); // this may throw, in such case don't process this scope (and possibly its subscopes if it was master scope)
-      if (scope_data == null) return;
-
-      var scope_node = new ScopeRegistryNode ()
-      {
-        scope_info = scope_data,
-        sub_scopes = null
-      };
-
-      // adding the scope_node now, but we'll update its fields if it's a master
-      scopes_.append (scope_node);
-
-      if (!scope_data.is_master) return;
-
-      /* This is a master scope, find its children */
-
-      // does the master scope hardcode its children?
-      unowned string[] subscopes = scope_data.get_subscope_ids ();
-      if (subscopes.length > 0)
-      {
-        foreach (unowned string subscope_id in subscopes)
+      var registry = new ScopeRegistry ();
+      Node<ScopeMetadata?> root_node = new Node<ScopeMetadata?> (null);
+      if (start_path == null)
+      {
+        foreach (unowned string scope_dir in scope_directories)
         {
+          if (!FileUtils.test (scope_dir, FileTest.IS_DIR)) continue;
           try
           {
-            ScopeMetadata subscope_data = ScopeMetadata.for_id (subscope_id);
-            if (scope_node.sub_scopes == null)
-              scope_node.sub_scopes = new GLib.SList<ScopeMetadata?> ();
-
-            scope_node.sub_scopes.append (subscope_data);
+            yield build_scope_node_tree (root_node, scope_dir);
           }
           catch (Error e)
           {
-            warning ("Failed to process '%s': %s", subscope_id, e.message);
+            // we'll ignore errors from here
+            warning ("Unable to process scope directory %s: %s",
+                     scope_dir, e.message);
           }
         }
       }
       else
       {
-        // check if there is a subdirectory with the name of master scope.
-        // note that failure on single sub-scope shouldn't disable master & valid sub-scopes.
-        var scopefile = GLib.File.new_for_path (scope_data.full_path);
-        string scope_name = remove_scope_extension (scope_data.id);
-        var parent = scopefile.get_parent ();
-        if (parent == null) return;
-
-        string check_path = Path.build_filename (parent.get_path (), scope_name);
-
-        if (!FileUtils.test (check_path, FileTest.IS_DIR)) return;
-
-        GLib.Dir? scope_subdir = null;
-        try
-        {
-          scope_subdir = GLib.Dir.open (check_path);
-        }
-        catch (FileError e)
-        {
-          warning ("Error accessing directory %s", check_path);
-        }
-
-        if (scope_subdir == null) return;
-
-        // iterate over all files, find .*scope
-        string slave_scope_filename;
-        while ((slave_scope_filename = scope_subdir.read_name ()) != null)
-        {
-          slave_scope_filename = Path.build_filename (check_path, slave_scope_filename);
-          try
-          {
-            ScopeMetadata slave_scope_data = ScopeMetadata.for_path (slave_scope_filename);
-            if (scope_node.sub_scopes == null)
-              scope_node.sub_scopes = new GLib.SList<ScopeMetadata?> ();
-
-            scope_node.sub_scopes.append (slave_scope_data);
-          }
-          catch (Error e)
-          {
-            warning ("Failed to process '%s': %s", slave_scope_filename, e.message);
-          }
-        }
+        yield build_scope_node_tree (root_node, start_path);
       }
-    }
-
-    /**
-     * Build registry of all scopes in start_path.
-     * start_path can be a directory, a .scope file path or just scope id (.scope file name, including extenstion).
-     *
-     * @param start_path starting directory or specific .scope file
-     * @return registry of all scopes (if start_path is a dir) or just one scope and its subscopes.
-     */
-    public static async ScopeRegistry find_scopes (string start_path) throws Error
-    {
-      var reg = yield find_scopes_for_master (start_path);
-      return reg;
-    }
-
-    /**
-     * Build registry of all scopes in start_path.
-     * start_path can be a directory, a .scope file path or just scope id (.scope file name, including extenstion).
-     *
-     * @param start_path starting directory or specific .scope file
-     * @return registry of all scopes (if start_path is a dir) or just one scope and its subscopes.
-     */
-    private static async ScopeRegistry find_scopes_for_master (string start_path) throws Error
-    {
-      debug ("find_scopes_for_master: %s\n", start_path);
-
-      var reg = new ScopeRegistry ();
-
+
+      registry.from_tree (root_node);
+      return registry;
+    }
+
+    private static bool node_has_child_with_id (Node<ScopeMetadata> node,
+                                                string scope_id,
+                                                out unowned Node<ScopeMetadata> child)
+    {
+      bool scope_id_present = false;
+      unowned Node<ScopeMetadata> found_child = null;
+      node.children_foreach (TraverseFlags.ALL, (child_) =>
+      {
+        unowned Node<ScopeMetadata> child_node = child_;
+        if (child_node.data.id == scope_id)
+        {
+          scope_id_present = true;
+          found_child = child_node;
+        }
+      });
+
+      child = found_child;
+
+      return scope_id_present;
+    }
+
+    private static async void build_scope_node_tree (Node<ScopeMetadata> root_node,
+                                                     string start_path)
+      throws Error
+    {
+      debug ("build_scope_node_tree [level: %u]: %s", root_node.depth (), start_path);
       if (FileUtils.test (start_path, FileTest.IS_DIR))
       {
         var dir = GLib.Dir.open (start_path);
@@ -693,33 +704,108 @@
         while ((name = dir.read_name ()) != null)
         {
           string filename = Path.build_filename (start_path, name);
-          if (filename.has_suffix (".scope"))
-          {
-            debug ("Found scope file: %s", filename);
-            try // failure of single scope shouldn't break processing of others scopes
-            {
-              yield reg.process_scope (filename);
-            }
-            catch (Error e)
-            {
-              warning ("Failed to process '%s': %s", filename, e.message);
-            }
+          if (!filename.has_suffix (".scope")) continue;
+          // failure of single scope shouldn't break processing of others scopes
+          try
+          {
+            yield build_scope_node_tree (root_node, filename);
+          }
+          catch (Error e)
+          {
+            warning ("Failed to process '%s': %s", filename, e.message);
           }
         }
       }
       else
       {
-        if (start_path.has_suffix (".scope"))
-        {
-          yield reg.process_scope (start_path); // no try-catch here, as request for specific scope file should fail on error
-        }
-        else
-        {
-          throw new ParseError.UNKNOWN_FILE ("Unknown file type");
+        if (!start_path.has_suffix (".scope"))
+        {
+          throw new ParseError.UNKNOWN_FILE ("Unknown file type: \"%s\"", start_path);
+        }
+        debug ("Found scope file: %s", start_path);
+        // this may throw, in such case don't process this scope
+        // (and possibly its subscopes if it was master scope)
+        ScopeMetadata? scope_data = ScopeMetadata.for_path (start_path);
+        if (scope_data == null) return;
+
+        // do we already have this scope in the tree?
+        unowned Node<ScopeMetadata> child_node = null;
+        bool scope_id_present = node_has_child_with_id (root_node,
+                                                        scope_data.id,
+                                                        out child_node);
+
+        if (!scope_id_present)
+        {
+          // save the node in the tree
+          child_node = root_node.append_data (scope_data);
+        }
+
+        assert (child_node != null);
+
+        if (child_node.data.is_master)
+        {
+          // if master scope specifies its subscopes, don't try to merge
+          // the children from multiple locations
+          if (child_node.data.get_overrides_subscopes () &&
+              child_node.n_children () == 0)
+          {
+            debug ("Scope %s overrides its children", child_node.data.id);
+            unowned string[] subscopes = child_node.data.get_subscope_ids ();
+            foreach (unowned string subscope_id in subscopes)
+            {
+              try
+              {
+                ScopeMetadata subscope_data = ScopeMetadata.for_id (subscope_id);
+                if (subscope_data != null &&
+                    !node_has_child_with_id (child_node, subscope_data.id, null))
+                {
+                  // FIXME: we're not building the complete tree here,
+                  // but right now it's not needed
+                  child_node.append_data (subscope_data);
+                }
+              }
+              catch (Error e)
+              {
+                warning ("Failed to process '%s': %s", subscope_id, e.message);
+              }
+            }
+          }
+          else
+          {
+            /* This is a master scope, find its children in subdirectory */
+            var scopefile = GLib.File.new_for_path (scope_data.full_path);
+            var parent = scopefile.get_parent ();
+            if (parent == null) return;
+            string scope_name = remove_scope_extension (scope_data.id);
+
+            string check_path = Path.build_filename (parent.get_path (), scope_name);
+            if (!FileUtils.test (check_path, FileTest.IS_DIR)) return;
+            yield build_scope_node_tree (child_node, check_path);
+          }
         }
       }
-      debug ("find_scopes_for_master finished");
-      return reg;
+    }
+
+    private void from_tree (Node<ScopeMetadata> root_node)
+    {
+      // only 2 level traverse, anything deeper will be discarded
+      root_node.children_foreach (TraverseFlags.ALL, (top_child_) =>
+      {
+        unowned Node<ScopeMetadata> top_child = top_child_;
+        var scope_node = new ScopeRegistryNode ()
+        {
+          scope_info = top_child.data,
+          sub_scopes = new GLib.SList<ScopeMetadata?> ()
+        };
+
+        top_child.children_foreach (TraverseFlags.ALL, (child_) =>
+        {
+          unowned Node<ScopeMetadata> child = child_;
+          scope_node.sub_scopes.append (child.data);
+        });
+
+        this.scopes_.append (scope_node);
+      });
     }
 
     internal static string remove_scope_extension (string scope_id)
@@ -738,64 +824,49 @@
      */
     public static async ScopeRegistry find_scopes_for_id (string scope_id, string? root_path = null) throws Error
     {
+      var registry = new ScopeRegistry ();
       debug ("find_scopes_for_id: %s", scope_id);
 
-      string[]? dirs = null;
-      if (root_path == null)
-      {
-        dirs = GLib.Environment.get_system_data_dirs ();
-      }
-      else
-      {
-        dirs = new string [1] {root_path};
-      }
-
-      if (dirs == null || dirs.length == 0)
-      {
-        throw new ParseError.INVALID_PATH ("Invalid scopes path");
-      }
-
+      var root_node = new Node<ScopeMetadata?> (null);
       // try to find the master scope file
       try
       {
-        var master_scope_metadata = ScopeMetadata.for_id (scope_id);
-        unowned string[] subscopes = master_scope_metadata.get_subscope_ids ();
-        if (subscopes.length > 0)
-        {
-          var reg = new ScopeRegistry ();
-          foreach (unowned string subscope_id in subscopes)
-          {
-            var node = new ScopeRegistryNode ();
-            try
-            {
-              node.scope_info = ScopeMetadata.for_id (subscope_id);
-              reg.scopes_.append (node);
-            }
-            catch (Error err)
-            {
-            }
-          }
-          return reg;
-        }
+        var scope_metadata = ScopeMetadata.for_id (scope_id);
+        yield build_scope_node_tree (root_node, scope_metadata.full_path);
+        if (scope_file_prefixes == null) init_scope_file_prefixes ();
       }
       catch (Error err)
       {
         // silently ignore
       }
 
-      var sc = remove_scope_extension (scope_id);
+      /* if the scope was found, we need to check also the other
+       * scope_directories, and merge sub-scopes from all of them, if it wasn't
+       * this wasn't a valid scope_id, perhaps we can find a dir? */
+      string[]? dirs = root_path == null ?
+        scope_directories : new string [1] { root_path };
+
+      if (dirs == null || dirs.length == 0)
+      {
+        throw new ParseError.INVALID_PATH ("Invalid scopes path");
+      }
+
+      unowned Node<ScopeMetadata?> node = root_node.n_children () > 0 ?
+        root_node.first_child () : root_node;
+
+      var suffix = remove_scope_extension (scope_id);
       foreach (var path in dirs)
       {
-        var check_path = root_path == null ? Path.build_path (Path.DIR_SEPARATOR_S, path, SCOPES_DIR, sc) : Path.build_path (Path.DIR_SEPARATOR_S, root_path, sc);
-        if (FileUtils.test (check_path, FileTest.IS_DIR))
-        {
-          var reg = yield find_scopes_for_master (check_path);
-          return reg;
-        }
+        var check_path = Path.build_filename (path, suffix);
+        if (!FileUtils.test (check_path, FileTest.IS_DIR)) continue;
+
+        yield build_scope_node_tree (node, check_path);
       }
 
-      debug ("No sub-scopes directory found for master scope %s", scope_id);
-      return new ScopeRegistry ();
+      // the registry from this method is not expected to contain the scope
+      // itself, so don't use the root directly
+      registry.from_tree (node);
+      return registry;
     }
   }
 

=== added directory 'test/data/unity/customized_scopes'
=== added directory 'test/data/unity/customized_scopes/masterscope_b'
=== added file 'test/data/unity/customized_scopes/masterscope_b.scope'
--- test/data/unity/customized_scopes/masterscope_b.scope	1970-01-01 00:00:00 +0000
+++ test/data/unity/customized_scopes/masterscope_b.scope	2013-09-06 15:44:22 +0000
@@ -0,0 +1,43 @@
+[Scope]
+GroupName=com.canonical.Unity.Scope.MasterB
+UniqueName=/com/canonical/unity/scope/masterb
+Icon=/usr/share/unity/6/icon2.svg
+IsMaster=true
+RequiredMetadata=bid[s];a[s];b[y];
+OptionalMetadata=
+# Keywords is localized
+Keywords=misc;booze;
+Type=booze
+QueryPattern=^(
+Name=Sample Master Scope 2
+Description=Find even more stuff
+SearchHint=Search things
+Shortcut=w
+NoContentHint=Sorry to make you a sad panda, but there's nothing here.
+
+[Desktop Entry]
+X-Ubuntu-Gettext-Domain=fakedomain
+
+[Category cat1]
+Name=Category #1
+Icon=/usr/share/unity/category1_icon.svg
+DedupField=uri
+
+[Category cat2]
+Name=Category #2
+Icon=/usr/share/unity/category2_icon.svg
+Renderer=list
+ContentType=music
+SortField=title
+
+[Filter genre]
+Name=Genre
+Type=check-options
+OptionIDs=bluez;pop;jazz;electro;
+OptionNames=Bluez;Pop;Jazz;Electro;
+
+[Filter decade]
+Name=Decade
+Type=multi-range
+OptionIDs=70;80;90;
+OptionNames=70s;80s;90s;

=== added file 'test/data/unity/customized_scopes/masterscope_b/subscope-custom.scope'
--- test/data/unity/customized_scopes/masterscope_b/subscope-custom.scope	1970-01-01 00:00:00 +0000
+++ test/data/unity/customized_scopes/masterscope_b/subscope-custom.scope	2013-09-06 15:44:22 +0000
@@ -0,0 +1,12 @@
+[Scope]
+GroupName=com.canonical.Unity.Scope.SubscopeCustom
+UniqueName=/com/canonical/unity/scope/subscope-custom
+Icon=/usr/share/unity/icon-sub.svg
+RequiredMetadata=bid[s];
+OptionalMetadata=
+Keywords=misc;
+Type=varia
+QueryPattern=^@
+Name=Sample custom subscope
+Description=Find various stuff subscope
+SearchHint=Search stuff subscope

=== modified file 'test/vala/test-scope-discovery.vala'
--- test/vala/test-scope-discovery.vala	2013-07-30 16:15:18 +0000
+++ test/vala/test-scope-discovery.vala	2013-09-06 15:44:22 +0000
@@ -18,6 +18,11 @@
  */
 using Unity;
 
+// a small hack for a bunch of internal protolib functions, that are useful
+public extern void unity_protocol_scope_registry_scope_metadata_update_hidden_scope_ids ();
+public extern void unity_protocol_scope_registry_init_scope_directories ();
+public extern void unity_protocol_scope_registry_init_scope_file_prefixes ();
+
 namespace Unity.Test
 {
   public class ScopeDiscoveryTestSuite
@@ -25,15 +30,21 @@
     public static const string SCOPES_ROOT = Config.TESTDIR + "/data/unity/scopes";
     const string PROTO_DOMAIN = "libunity-protocol-private";
 
+    const int NUM_TOP_LEVEL_TEST_SCOPES = 4;
+
     public ScopeDiscoveryTestSuite ()
     {
       GLib.Environment.set_variable ("XDG_DATA_DIRS", Config.TESTDIR + "/data", true);
+      GLib.Environment.set_variable ("LIBUNITY_SCOPE_DIRECTORIES", Config.TESTDIR + "/data/unity/scopes", true);
 
       GLib.Test.add_data_func ("/Unit/ScopeMetadata/LoadScopeById", ScopeDiscoveryTestSuite.test_metadata_load_by_scope_id);
       GLib.Test.add_data_func ("/Unit/ScopeMetadata/LoadMasterscope", ScopeDiscoveryTestSuite.test_metadata_load_masterscope);
       GLib.Test.add_data_func ("/Unit/ScopeDiscovery/FindScopes", ScopeDiscoveryTestSuite.test_find_all_scopes);
+      GLib.Test.add_data_func ("/Unit/ScopeDiscovery/FindScopesInXdg", ScopeDiscoveryTestSuite.test_find_all_scopes_xdg);
+      GLib.Test.add_data_func ("/Unit/ScopeDiscovery/FindScopesWithHidden", ScopeDiscoveryTestSuite.test_find_all_scopes_with_hidden_scopes);
       GLib.Test.add_data_func ("/Unit/ScopeDiscovery/FindSpecificScopes", ScopeDiscoveryTestSuite.test_find_specific_scope);
       GLib.Test.add_data_func ("/Unit/ScopeDiscovery/FindScopeById", ScopeDiscoveryTestSuite.test_find_scope_by_id);
+      GLib.Test.add_data_func ("/Unit/ScopeDiscovery/FindOverriddenScopeById", ScopeDiscoveryTestSuite.test_find_overridden_scope_by_id);
     }
 
     internal static void check_scope_b_subscopes (Protocol.ScopeRegistry.ScopeRegistryNode node)
@@ -94,90 +105,260 @@
       Protocol.ScopeRegistry reg = null;
 
       var ml = new MainLoop ();
-      Protocol.ScopeRegistry.find_scopes.begin (SCOPES_ROOT,
-      (obj, res) =>
-      {
-        reg = Protocol.ScopeRegistry.find_scopes.end (res);
-        ml.quit ();
-      });
-
-      run_with_timeout (ml, 5000);
-
-      assert (reg != null);
-      assert (reg.scopes != null);
-      assert (reg.scopes.length () >= 2); // there are exactly 2 top-level scopes (master scopes)
-
-      bool got_masterscope_1 = false;
-      bool got_masterscope_2 = false;
-      bool got_masterscope_3 = false;
-
-      foreach (var node in reg.scopes)
-      {
-        assert (node != null);
-        var inf = node.scope_info;
-        if (inf.name == "Sample Master Scope 1")
-        {
-          assert (inf.id == "masterscope_a.scope");
-          assert (inf.dbus_name == "com.canonical.Unity.Scope.MasterA");
-          assert (inf.dbus_path == "/com/canonical/unity/scope/mastera");
-          assert (inf.is_master == true);
-          assert (inf.icon == "/usr/share/unity/6/icon1.svg");
-          assert (inf.required_metadata.columns.length == 3);
-          var col = inf.required_metadata.columns[0];
-          assert (col.name == "some_id");
-          assert (col.type_id == "s");
-          col = inf.required_metadata.columns[1];
-          assert (col.name == "foo");
-          assert (col.type_id == "s");
-          col = inf.required_metadata.columns[2];
-          assert (col.name == "bar");
-          assert (col.type_id == "y");
-          assert (inf.optional_metadata != null);
-          assert (inf.optional_metadata.columns.length == 1);
-          col = inf.optional_metadata.columns[0];
-          assert (col.name == "baz");
-          assert (col.type_id == "u");
-          assert (inf.keywords.length () == 1);
-          assert (inf.type == "varia");
-          assert (inf.query_pattern == "");
-          assert (inf.description == "Find various stuff");
-          assert (inf.search_hint == "Search stuff");
-          assert (node.sub_scopes == null);
-
-          got_masterscope_1 = true;
-        }
-        else if (inf.name == "Sample Master Scope 2")
-        {
-          assert (inf.id == "masterscope_b.scope");
-          assert (inf.dbus_name == "com.canonical.Unity.Scope.MasterB");
-          assert (inf.dbus_path == "/com/canonical/unity/scope/masterb");
-          assert (inf.is_master == true);
-          assert (inf.icon == "/usr/share/unity/6/icon2.svg");
-          assert (inf.keywords.length () == 2);
-          assert (inf.keywords.nth_data (0) == "misc");
-          assert (inf.keywords.nth_data (1) == "booze");
-          assert (inf.type == "booze");
-          assert (inf.query_pattern == "^(");
-          assert (inf.description == "Find even more stuff");
-          assert (inf.search_hint == "Search things");
-
-          check_scope_b_subscopes (node);
-
-          got_masterscope_2 = true;
-        }
-        else if (inf.name == "Sample Master Scope 3")
-        {
-          assert (inf.id == "masterscope_c.scope");
-
-          assert (node.sub_scopes.length () == 1);
-          assert (node.sub_scopes.nth_data (0).id == "test_masterscope.scope");
-          got_masterscope_3 = true;
-        }
-      }
-
-      assert (got_masterscope_1 == true);
-      assert (got_masterscope_2 == true);
-      assert (got_masterscope_3 == true);
+      Protocol.ScopeRegistry.find_scopes.begin (SCOPES_ROOT, (obj, res) =>
+      {
+        reg = Protocol.ScopeRegistry.find_scopes.end (res);
+        ml.quit ();
+      });
+
+      run_with_timeout (ml, 5000);
+
+      assert (reg != null);
+      assert (reg.scopes != null);
+      assert (reg.scopes.length () == NUM_TOP_LEVEL_TEST_SCOPES);
+
+      bool got_masterscope_1 = false;
+      bool got_masterscope_2 = false;
+      bool got_masterscope_3 = false;
+
+      foreach (var node in reg.scopes)
+      {
+        assert (node != null);
+        var inf = node.scope_info;
+        if (inf.name == "Sample Master Scope 1")
+        {
+          assert (inf.id == "masterscope_a.scope");
+          assert (inf.dbus_name == "com.canonical.Unity.Scope.MasterA");
+          assert (inf.dbus_path == "/com/canonical/unity/scope/mastera");
+          assert (inf.is_master == true);
+          assert (inf.icon == "/usr/share/unity/6/icon1.svg");
+          assert (inf.required_metadata.columns.length == 3);
+          var col = inf.required_metadata.columns[0];
+          assert (col.name == "some_id");
+          assert (col.type_id == "s");
+          col = inf.required_metadata.columns[1];
+          assert (col.name == "foo");
+          assert (col.type_id == "s");
+          col = inf.required_metadata.columns[2];
+          assert (col.name == "bar");
+          assert (col.type_id == "y");
+          assert (inf.optional_metadata != null);
+          assert (inf.optional_metadata.columns.length == 1);
+          col = inf.optional_metadata.columns[0];
+          assert (col.name == "baz");
+          assert (col.type_id == "u");
+          assert (inf.keywords.length () == 1);
+          assert (inf.type == "varia");
+          assert (inf.query_pattern == "");
+          assert (inf.description == "Find various stuff");
+          assert (inf.search_hint == "Search stuff");
+          assert (node.sub_scopes == null);
+
+          got_masterscope_1 = true;
+        }
+        else if (inf.name == "Sample Master Scope 2")
+        {
+          assert (inf.id == "masterscope_b.scope");
+          assert (inf.dbus_name == "com.canonical.Unity.Scope.MasterB");
+          assert (inf.dbus_path == "/com/canonical/unity/scope/masterb");
+          assert (inf.is_master == true);
+          assert (inf.icon == "/usr/share/unity/6/icon2.svg");
+          assert (inf.keywords.length () == 2);
+          assert (inf.keywords.nth_data (0) == "misc");
+          assert (inf.keywords.nth_data (1) == "booze");
+          assert (inf.type == "booze");
+          assert (inf.query_pattern == "^(");
+          assert (inf.description == "Find even more stuff");
+          assert (inf.search_hint == "Search things");
+
+          check_scope_b_subscopes (node);
+
+          got_masterscope_2 = true;
+        }
+        else if (inf.name == "Sample Master Scope 3")
+        {
+          assert (inf.id == "masterscope_c.scope");
+
+          assert (node.sub_scopes.length () == 1);
+          assert (node.sub_scopes.nth_data (0).id == "test_masterscope.scope");
+          got_masterscope_3 = true;
+        }
+      }
+
+      assert (got_masterscope_1 == true);
+      assert (got_masterscope_2 == true);
+      assert (got_masterscope_3 == true);
+    }
+
+    internal static void test_find_all_scopes_xdg ()
+    {
+      // ignore warnings
+      var error_handler = new ErrorHandler ();
+      error_handler.ignore_message (PROTO_DOMAIN, LogLevelFlags.LEVEL_WARNING);
+
+      Protocol.ScopeRegistry reg = null;
+
+      var ml = new MainLoop ();
+      Protocol.ScopeRegistry.find_scopes.begin (null, (obj, res) =>
+      {
+        reg = Protocol.ScopeRegistry.find_scopes.end (res);
+        ml.quit ();
+      });
+
+      run_with_timeout (ml, 5000);
+
+      assert (reg != null);
+      assert (reg.scopes != null);
+      assert (reg.scopes.length () == NUM_TOP_LEVEL_TEST_SCOPES);
+
+      bool got_masterscope_1 = false;
+      bool got_masterscope_2 = false;
+      bool got_masterscope_3 = false;
+
+      foreach (var node in reg.scopes)
+      {
+        assert (node != null);
+        var inf = node.scope_info;
+        if (inf.name == "Sample Master Scope 1")
+        {
+          assert (inf.id == "masterscope_a.scope");
+          assert (inf.dbus_name == "com.canonical.Unity.Scope.MasterA");
+          assert (inf.dbus_path == "/com/canonical/unity/scope/mastera");
+          assert (inf.is_master == true);
+          assert (inf.icon == "/usr/share/unity/6/icon1.svg");
+          assert (inf.required_metadata.columns.length == 3);
+          var col = inf.required_metadata.columns[0];
+          assert (col.name == "some_id");
+          assert (col.type_id == "s");
+          col = inf.required_metadata.columns[1];
+          assert (col.name == "foo");
+          assert (col.type_id == "s");
+          col = inf.required_metadata.columns[2];
+          assert (col.name == "bar");
+          assert (col.type_id == "y");
+          assert (inf.optional_metadata != null);
+          assert (inf.optional_metadata.columns.length == 1);
+          col = inf.optional_metadata.columns[0];
+          assert (col.name == "baz");
+          assert (col.type_id == "u");
+          assert (inf.keywords.length () == 1);
+          assert (inf.type == "varia");
+          assert (inf.query_pattern == "");
+          assert (inf.description == "Find various stuff");
+          assert (inf.search_hint == "Search stuff");
+          assert (node.sub_scopes == null);
+
+          got_masterscope_1 = true;
+        }
+        else if (inf.name == "Sample Master Scope 2")
+        {
+          assert (inf.id == "masterscope_b.scope");
+          assert (inf.dbus_name == "com.canonical.Unity.Scope.MasterB");
+          assert (inf.dbus_path == "/com/canonical/unity/scope/masterb");
+          assert (inf.is_master == true);
+          assert (inf.icon == "/usr/share/unity/6/icon2.svg");
+          assert (inf.keywords.length () == 2);
+          assert (inf.keywords.nth_data (0) == "misc");
+          assert (inf.keywords.nth_data (1) == "booze");
+          assert (inf.type == "booze");
+          assert (inf.query_pattern == "^(");
+          assert (inf.description == "Find even more stuff");
+          assert (inf.search_hint == "Search things");
+
+          check_scope_b_subscopes (node);
+
+          got_masterscope_2 = true;
+        }
+        else if (inf.name == "Sample Master Scope 3")
+        {
+          assert (inf.id == "masterscope_c.scope");
+
+          assert (node.sub_scopes.length () == 1);
+          assert (node.sub_scopes.nth_data (0).id == "test_masterscope.scope");
+          got_masterscope_3 = true;
+        }
+      }
+
+      assert (got_masterscope_1 == true);
+      assert (got_masterscope_2 == true);
+      assert (got_masterscope_3 == true);
+    }
+
+    internal static void test_find_all_scopes_with_hidden_scopes ()
+    {
+      var settings = new Settings ("com.canonical.Unity.Lenses");
+      settings.set_strv ("hidden-scopes",
+                         {"masterscope_a.scope", "test_masterscope.scope"});
+      unity_protocol_scope_registry_scope_metadata_update_hidden_scope_ids ();
+      // ignore warnings
+      var error_handler = new ErrorHandler ();
+      error_handler.ignore_message (PROTO_DOMAIN, LogLevelFlags.LEVEL_WARNING);
+
+      Protocol.ScopeRegistry reg = null;
+
+      var ml = new MainLoop ();
+      Protocol.ScopeRegistry.find_scopes.begin (null, (obj, res) =>
+      {
+        reg = Protocol.ScopeRegistry.find_scopes.end (res);
+        ml.quit ();
+      });
+
+      run_with_timeout (ml, 5000);
+
+      assert (reg != null);
+      assert (reg.scopes != null);
+      // there are exactly 4 top-level scopes (master scopes) - 2 disabled
+      assert (reg.scopes.length () == NUM_TOP_LEVEL_TEST_SCOPES - 2);
+
+      bool got_masterscope_1 = false;
+      bool got_masterscope_2 = false;
+      bool got_masterscope_3 = false;
+
+      foreach (var node in reg.scopes)
+      {
+        assert (node != null);
+        var inf = node.scope_info;
+        if (inf.name == "Sample Master Scope 1")
+        {
+          assert (inf.id == "masterscope_a.scope");
+          got_masterscope_1 = true;
+        }
+        else if (inf.name == "Sample Master Scope 2")
+        {
+          assert (inf.id == "masterscope_b.scope");
+          assert (inf.dbus_name == "com.canonical.Unity.Scope.MasterB");
+          assert (inf.dbus_path == "/com/canonical/unity/scope/masterb");
+          assert (inf.is_master == true);
+          assert (inf.icon == "/usr/share/unity/6/icon2.svg");
+          assert (inf.keywords.length () == 2);
+          assert (inf.keywords.nth_data (0) == "misc");
+          assert (inf.keywords.nth_data (1) == "booze");
+          assert (inf.type == "booze");
+          assert (inf.query_pattern == "^(");
+          assert (inf.description == "Find even more stuff");
+          assert (inf.search_hint == "Search things");
+
+          check_scope_b_subscopes (node);
+
+          got_masterscope_2 = true;
+        }
+        else if (inf.name == "Sample Master Scope 3")
+        {
+          assert (inf.id == "masterscope_c.scope");
+
+          // the child in this one is disabled, there should be 0 subscopes
+          assert (node.sub_scopes.length () == 0);
+          got_masterscope_3 = true;
+        }
+      }
+
+      assert (got_masterscope_1 == false);
+      assert (got_masterscope_2 == true);
+      assert (got_masterscope_3 == true);
+
+      // cleanup
+      settings.set_strv ("hidden-scopes", {});
+      unity_protocol_scope_registry_scope_metadata_update_hidden_scope_ids ();
     }
 
     internal static void test_find_specific_scope ()
@@ -229,17 +410,20 @@
 
     internal static void test_find_scope_by_id ()
     {
-      // ignore warnings
+      // ignore warnings, because there's broken scope in the dir
       var error_handler = new ErrorHandler ();
       error_handler.ignore_message (PROTO_DOMAIN, LogLevelFlags.LEVEL_WARNING);
 
       Protocol.ScopeRegistry reg = null;
 
       var ml = new MainLoop ();
-      Protocol.ScopeRegistry.find_scopes_for_id.begin ("masterscope_b.scope", null,
-      (obj, res) =>
+      Protocol.ScopeRegistry.find_scopes_for_id.begin ("masterscope_b.scope", null, (obj, res) =>
       {
-        reg = Protocol.ScopeRegistry.find_scopes_for_id.end (res);
+        try
+        {
+          reg = Protocol.ScopeRegistry.find_scopes_for_id.end (res);
+        }
+        catch (Error e) { assert_not_reached (); }
         ml.quit ();
       });
 
@@ -247,12 +431,76 @@
 
       assert (reg != null);
       assert (reg.scopes != null);
-      assert (reg.scopes.length () == 2); // there are exactly 2 top-level scopes (sub-scopes of masterscope_b)
+      assert (reg.scopes.length () == 2); // there are exactly 2 scopes (sub-scopes of masterscope_b)
 
       var node = reg.scopes.nth_data (0);
       assert (node != null);
     }
 
+    internal static void test_find_overridden_scope_by_id ()
+    {
+      string[] extra_dirs = {
+        Config.TESTDIR + "/data/unity/customized_scopes",
+        Config.TESTDIR + "/data/non_existant",
+        Config.TESTDIR + "/data/unity/scopes",
+      };
+      string dirs = string.joinv (":", extra_dirs);
+      Environment.set_variable ("LIBUNITY_SCOPE_DIRECTORIES", dirs, true);
+      unity_protocol_scope_registry_init_scope_directories ();
+      unity_protocol_scope_registry_init_scope_file_prefixes ();
+
+      // ignore warnings, because there's broken scope in the dir
+      var error_handler = new ErrorHandler ();
+      error_handler.ignore_message (PROTO_DOMAIN, LogLevelFlags.LEVEL_WARNING);
+
+      Protocol.ScopeRegistry reg = null;
+
+      var ml = new MainLoop ();
+      Protocol.ScopeRegistry.find_scopes_for_id.begin ("masterscope_b.scope", null, (obj, res) =>
+      {
+        try
+        {
+          reg = Protocol.ScopeRegistry.find_scopes_for_id.end (res);
+        }
+        catch (Error e) { assert_not_reached (); }
+        ml.quit ();
+      });
+
+      run_with_timeout (ml, 5000);
+
+      assert (reg != null);
+      assert (reg.scopes != null);
+      assert (reg.scopes.length () == 3); // there are exactly 3 scopes (sub-scopes of masterscope_b)
+
+      bool found_subscope1 = false;
+      bool found_subscope2 = false;
+      bool found_override = false;
+      foreach (var node in reg.scopes)
+      {
+        switch (node.scope_info.id)
+        {
+          case "masterscope_b-subscope1.scope": found_subscope1 = true;
+            break;
+          case "masterscope_b-subscope2.scope": found_subscope2 = true;
+            break;
+          case "masterscope_b-subscope-custom.scope": found_override = true;
+            break;
+          default: warning ("Found unknown subscope: %s", node.scope_info.id);
+            break;
+        }
+      }
+
+      assert (found_subscope1);
+      assert (found_subscope2);
+      assert (found_override);
+
+      // cleanup
+      Environment.set_variable ("LIBUNITY_SCOPE_DIRECTORIES",
+        "%s/data/unity/scopes".printf (Config.TESTDIR), true);
+      unity_protocol_scope_registry_init_scope_directories ();
+      unity_protocol_scope_registry_init_scope_file_prefixes ();
+    }
+
     internal static void test_metadata_load_by_scope_id ()
     {
       var metadata = Protocol.ScopeRegistry.ScopeMetadata.for_id ("masterscope_a.scope");