Skip to content

docs(ignoring): document .stglobalignore shared ignore patterns #1016

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
grantstephens wants to merge 1 commit into
base: main
Choose a base branch
from
+21 −3
Open

docs(ignoring): document .stglobalignore shared ignore patterns #1016

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 21 additions & 3 deletions users/ignoring.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ Synopsis
::

.stignore
.stglobalignore

Description
-----------
Expand All @@ -23,6 +24,16 @@ although it can ``#include`` files that *are* synchronized between devices. All
patterns are relative to the synced folder root. The contents of the ``.stignore``
file must be UTF-8 encoded.

A second file called ``.stglobalignore`` can be placed in the folder root to hold
patterns that should be shared across all devices. Unlike ``.stignore``, the
``.stglobalignore`` file *is* synchronized between devices, so patterns written there
are automatically propagated when the folder syncs to a new host — no manual setup on
each device is required. Patterns from ``.stglobalignore`` are appended after those in ``.stignore``.
Because the first matching pattern wins, ``.stignore`` always takes precedence:
any pattern in ``.stignore`` — whether an ignore or a negation — will override
a conflicting pattern in ``.stglobalignore``.
If ``.stglobalignore`` does not exist the folder loads normally with no error.

.. note::

Note that ignored files can block removal of an otherwise empty directory.
Expand Down Expand Up @@ -207,7 +218,14 @@ all files and directories called "foo", ending in a "2" or starting with

.. versionadded:: 2.0.0

Windows users can now use the pipe character (``|``) to escape
metacharacters in the ``.stignore`` file. Additionally, adding
``#escape=X`` to the top of the file, allows users to define ``X``
Windows users can now use the pipe character (``|``) to escape
metacharacters in the ``.stignore`` file. Additionally, adding
``#escape=X`` to the top of the file, allows users to define ``X``
as the escape character for that particular file.

.. versionadded:: 2.2.0

``.stglobalignore`` is now automatically loaded alongside ``.stignore``.
Patterns in ``.stglobalignore`` are synced between devices, removing the
need to manually configure ignore patterns on each host. See the
description above for precedence rules.