Where can I find documentation on how to use ignore.conf?

[bochulindra]

I'm looking for detailed rules on how ignore.conf works. I can't find documentation anywhere. I'm currently getting bits and pieces of information from posts in the forums.

 

Is there official documentation anywhere and if not, why not?

 

Specifically, I want to know what happens when there's rules in ignore.conf that conflict (eg one rule ignores everything in a folder but another rule uses ! to exclude a specific file in that folder).

 

But what I really want to know is where the documentation is.

[manu]

Hi!

 

Specifically, I want to know what happens when there's rules in ignore.conf that conflict (eg one rule ignores everything in a folder but another rule uses ! to exclude a specific file in that folder).

 

Something like:

bin/*
!*bin/sb2.x

Will ignore all inside bin directory but the sb2.x file... because there's an exclusion rule.

 

There's not a guide regarding the ignore.conf file but almost everything can be done using the GUI options to include/exclude items...

 

I can give you some basic examples:

*.cs                 -> All the .cs files in the workspace will be ignored.
*/src/*.js           -> Will ignore all the ‘js’ files inside a directory called ‘src’.
*/src/**/*.js        -> Will ignore all the ‘js’ files inside any directory inside a directory called ‘src’
*/src/**/*x.js       -> Will ignore all the ‘x.js’ files inside any directory inside a directory called ‘src’
ignore.conf          -> Will ignore all the files called "ignore.conf" inside the workspace.
!*/src/CmdRunner.cs  -> Will not ignore the "/src/CmdRunner.cs" file

If you have any other scenario you need to know how to do it we can help you.

[bochulindra]

Awesome, thanks for those examples.

 

What if I have something like this?

!bin/*
bin/foo

Is bin/foo included or excluded?

[calbzam]

Hi,

 

In that case, "foo" will be ignored.  

 

The ! rules will be applied first, and then the rest of the rules.

 

Regards,

Carlos.

[bochulindra]

I found a little bit of documentation here for anyone that would like more: http://blog.plasticscm.com/2014/11/configuring-ignored-items-on-your.html

[manu]

Don't forget reading the following content as well: 

• https://www.plasticscm.com/documentation/administration/plastic-scm-version-control-administrator-guide.shtml#Globalfileconfiguration
• https://www.plasticscm.com/documentation/user/plastic-scm-version-control-introduction-guide.shtml#C2_Getting_started_Filtering
• https://www.plasticscm.com/documentation/labs/main.shtml#Configuringtheignoredfileslist

[Johan Ung]

Hm not sure I fully understands the rules when it comes to wildcards, I'm trying to ignore build output directories (Debug_VS10 and Release_VS10) so I tried using the following:

*_VS10/

That didn't work, but this did:

*/**/*_VS10/

 

So no biggie, got it working and just wanted to mention it for future reference.

[manu]

Hi Johan!

Can you try again the first rule? It's working fine for me.

You can also try with just "*_VS10". Works for me as well.

[Johan Ung]

I forgot to mention that the directories has files within them.

If I add both:

*_VS10/

*_VS10/*

it seems to be working.

If I specify the directory names without wildcards, it is sufficient with only the directory rule:

Debug_VS10/

Release_VS10/

[manu]

Hi Johan,

yes, thank you for pointing it out. It might be confusing the fist time you see it. We'll try to study if we can improve it.

[M-Pixel]

On 11/28/2014 at 7:21 AM, calbzam said:

The ! rules will be applied first, and then the rest of the rules.

This is definitely not the case (at least, not in 2017, maybe it was in 2014).

Given ignore

*
!*.cs
obj

and workspace

ignore.conf
Program.cs
obj/
    someAutomaticallyGenerated.cs

someAutomaticallyGenerated.cs shows up despite the fact that its parent folder is ignored.

Even changing `obj` to `obj/**` did not change anything

[calbzam]

The `!*.cs` rules prevail over the other rules. If you remove this rule, you should be able tu use `obj`.

Regards,

Carlos.

[M-Pixel]

So, if I wanted to say "ignore everything in A except for cs files, and ignore absolutely everything including cs files in A/B", then that's impossible in Plastic SCM? That's very inconvenient for users of Unreal Engine because of the way it intersperses generated and downloaded files throughout the directory structure. Git supports this sort of arrangement very easily by giving increasing priority to each line in the ignore file.

[calbzam]

Could you try something like the following?

/a
!/a/*.cs
/a/b

Regards,

Carlos.

[headfuze]

@Carlos,

I've just hit this problem too. My project is ue4 based, so I need to set up an ignore file that deals with ue4's unwieldy file layout (generated files get interspersed with versioned files). As M-Pixel pointed out, this is very straightforward to handle with git. Git's ignore file honors "the principle of least surprise" and "the principle of least energy". Each pattern in the ignore file is evaluated in the order it is specified, from top to bottom, so the user isn't surprised by their instructions not being followed, and it is not necessary to issue redundant instructions, so the user doesn't have to spend more time and energy getting things done than absolutely necessary. Here's an example of a very straight forward gitignore file that works well for ue4 projects and is very easy to read and maintain: ue4 gitignore.

The problem with the solution you've proposed above is that it doesn't scale beyond extremely simple cases. If I want to not ignore a folder using Plastic's approach, I need to go in and explicitly specify all basic file patterns I want to ignore in that folder (temporary files like ".DS_Store" for example). If I want to not ignore another folder, I have to repeat that I want to ignore all those basic file patterns again for that other folder, and so on. If you look at the linked gitignore file above, to do the same thing in Plastic would end up being a pretty large ignore file - worse, there's now 'hidden knowledge' required for that to be maintained properly over time. Anyone coming to Plastic from git will be frustrated by this if they're used to git's flexibility.

Another issue with how Plastic works here is to do with commenting. In order for the above to have any chance of working over time it must be possible to have comments in the ignore file so that at least people have a shot at doing the right thing when they introduce an ignore pattern (like making sure to add it to multiple !paths). The issue is that if you add a pattern via the GUI, Plastic strips out all the blank lines and comments! (Surely this is a bug?) It happens on both Windows and Mac (I'm using Plastic Cloud 6.x). It also reorders the contents of the file to place all the ! patterns at the top of the file. 

The basic topology of an ignore file to handle unwieldy project layouts would ideally be along the lines of the linked file above which is:

1: Ignore everything

2: Don't ignore explicitly required files (project files etc.)

3: Don't ignore X, Y and Z directory patterns.

4: Ignore all the basic file patterns (like .DS_Store etc) which are now exposed by the whitelisted directories above.

The above executes the filtering process in the order the user specifies (honors the principle of least surprise), has no redundancy (honors the principle of least energy), and as a result is easy to read and understand, is therefore hard to break and most importantly does not require hidden knowledge to update correctly over time.

For now I'm working around it, but...

1: It would be good to get a bug fix in for the blank lines and comment stripping behavior of the Plastic GUI Add-to-ignored-list functionality.

2: Obviously you're not going to be able to change this outright, but If I could add a feature request it would be to add an "opt-in" setting to change the ignore file behavior to standardize it, and bring it in line with a 'what you see is what you get' approach as this is much more flexible, especially for project layouts that are unwieldy by nature. Low priority, but definitely worth considering from the perspective of not frustrating git power-users adopting Plastic.