Documentation for Filter Syntax

[jetchirag]

We'll need to update documentation to explain filtering options (borgbase/vorta#1749). I think we can add a link to the documentation beside the search icon. Where should the syntax go?

[m3nu]

If possible, a feature should explain itself. Very few people will read the docs, unless truly a lot of background explaining is needed.

[jetchirag]

I would want that too but not sure how to go about it. The syntax is not standard and would require do to see what does what. Though, Normal search which doesn't require any syntax would be enough for most use case. Do we need to add an interactive dialog to select filtering option?

…

On Tue, 26 Sept 2023, 03:27 Manu, ***@***.***> wrote: If possible, a feature should explain itself. Very few people will read the docs, unless truly a lot of background explaining is needed. — Reply to this email directly, view it on GitHub <#45 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADTXRDT3UD37I3ADRACUYHTX4H455ANCNFSM6AAAAAA5GWHYWE> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[m3nu]

Right. The syntax will need explaining. How long is that? Would that be a table or list or something?

[jetchirag]

I was thinking to make it similar to a man page.

This is the original syntax, final one is a bit modified.

[ string ] [ -m ] [ -i ] [ -p ] [ -c ] [ -s ]
Note: Search String and other options are all optional

Options/Flags:

	--match -m <type>
	Type of match query
	Supported values:
		in (default): Filename should contain search string
		exact: Filename must match the search string exactly
		re: Use regex to match filename    

	--ignore-case -i
	Ignore Case. Supported by `in` and `exact` match type only.	

	--path -p <path>
	Specify path to match. Supports wildcard. Parsed using glob (?)
	Example:
		--path /home/vorta/Documents
		--path /var/www/public/*
		--path */src/*
	
	--change -c <type>
	Only available in Diff View. Supported values:
		A: Match only Added files
		R: Match only Removed files
		...
	
	--size -s <relation[<|>]number[B|KB|MB|GB>]>
	Match by size. Can be combined once to create a range. Range must be bounded.
	Example:
		--size <10MB
		--size >1GB
		--size >1GB --size <10GB

[m3nu]

Since the docs are in markdown and Vorta isn't a CLI app, I'd suggest sticking to normal markdown format. Also to avoid anyone mistaking this syntax for actual CLI args. Something like:

---

Supported search parameters

Match by size

Can be combined once to create a range. Range must be bounded.

Examples:

• --size <10MB

[real-yfprojects]

A table might be quicker to read and find options in.

[real-yfprojects]

I would add a new page under Usage for this documentation.