Use filter pattern files#

Use filter pattern rules to set up specific client configuration files.

Pattern files are plain text files that contain one rule per line to match files according to their paths. Unity Version Control (UVCS) checks the path of each item to check if it’s affected by the set of rules. To comment lines, place the # character at the beginning of any line.

Filter pattern files in UVCS#

The following filter pattern files apply to the workspace or pending changes to specify how Unity Version Control (UVCS) filters items:

• Ignored files (ignore.conf)
• Cloaked files (cloaked.conf)
• Hidden changes (hidden_changes.conf)
• Writable and read-only files (writable.conf and readonly.conf)
  • These two files apply to the same action (set the item as read-only).
  • writable.conf takes precedence over readonly.conf.

Rule types#

UVCS has multiple types of rules that you can use in configuration files.

For more information on which rule types take precedence when you use multiple, refer to pattern hierarchy.

Absolute path rules#

Absolute path rules allow you to match a single file or directory.

# The following rule matches the complete workspace tre:
/
# The following rule matches:
#   * /src/main/test
#   * /src/main/test/com/package/BasicTests.java
/src/main/test
# The following rule only matches:
#   * /src/lib/server/Main.java
# But the rule doesn’t match these files:
#   * /Main.java
#   * /src/lib/client/Main.java
/src/lib/server/Main.java

Rules with wildcards#

Use wildcards to customize absolute path rules:

• * matches any number of consecutive characters except the directory separator /.
• ** matches any number of consecutive characters, including the directory separator /.
• ? matches a single character, excluding the directory separator /.

# The following matches:
#   * /src/lib-3/main.c
#   * /src/samples/number-3/main.c
/src/**-3/main.c

# The following matches:
#   * /doc/public/toc.tex
#   * /doc/public/chapter-1.tex
/doc/public/*.tex
# The following matches:
#   * /src/lib/code.c
#   * /src/lib/coda.c
/src/lib/cod?.c

Catch all rules#

Catch all rules are a subset of the wildcard rules. These rules are equivalent and match the complete workspace tree:

• /
• *
• /*
• */
• **
• /**
• **/

Item name rules#

Match files or directories according to their names:

# The following matches:
#   * /src/lib
#   * /src/lib/client/main.c
#   * /src/lib/test
#   * /references/lib
#   * /references/lib/libgit2.so
lib
# The following matches:
#   * /src/lib/references.c
#   * /references.c
#   * /doc/main/references.c
references.c

Extension rules#

Match files according to the file extension:

# The following matches:
#   * /src/main/java/com/samplepackage/Main.java
#   * /examples/ReferenceList.java
*.java
# The following matches:
#   * /bin/client/resources/core.en.resx
#   * /out/bin/server/resources/networking.en.resx
^*.en.resx$

Regular expression patterns#

Use regular expressions to match files. Ensure that the pattern starts with the ^ character and ends with the $ character:

# The following match:
#   * /src/doc/sample-3528.txt
#   * /sample-1.txt
^.*\/sample-[0-9]+.txt$
# The following match:
#   * /bin/dir-0xC0FFEE/main.c
#   * /publish/bin/dir-0xDADA_/backend.cpp
^.*\/dir-0x[A-F0-9]+_?\/[^\/]+$

Exclusion rules#

To use a rule to exclude an item from the filter, use the same rules but start the pattern with the ! character. For example, the following rules match the entire directory, but exclude the specified paths:

/
!/src/lib
!/main/bin/compiler.exe
!*.h
!references
!resources.*

Pattern hierarchy#

UVCS uses the patterns in a file to match the path of an item. Some pattern formats take precedence over others. The following shows the hierarchy of pattern formats:

1. Absolute path rules that match exactly
2. Catch-all rules
3. Name rules applied to the current item
4. Absolute path rules applied to the item directory structure
5. Name rules applied to the item directory structure
6. Extension rules
7. Wildcard and Regular expression rules

Exclusion rules order#

Exclusion rules take precedence over other rules, so UVCS matches those first. There are two exceptions to this rule:

• Absolute path rules that match exactly
• Absolute path rules applied to the item directory structure

Absolute path rules that match exactly#

UVCS applies absolute path rules that match exactly before exclusion rules. For example, if you use the following rules, UVCS filters the item /src/test/testdata.zip even though the exclusion rule prevents the entire directory from being filtered:

!/
/src/test/testdata.zip

Absolute path rules applied to the item directory structure#

UVCS applies absolute path rules applied to the item directory structure before exclusion rules. In this case, the most precise rule takes precedence.

For example, you can use the following rules:

/src
!/src/client
/src/client/bin

In this example, UVCS filters files such as /src/build.sh or /src/client/bin/output.so, but not a /src/client/socket.c file.