Configuring ignored items in your workspace
UPDATE 2019/01/23: Read the Pattern files chapter in the Plastic Book to find the complete information about how to configure the ignore.conf file.
UPDATE 2018/10/25: We added the "Learn more" section to show you some interesting configuration options about the items in your workspace.
On occasion, there are files that you don't want to submit to version control such as private IDE settings, intermediate build result files, binaries and so on.
This blog post explains how to handle this in Plastic by manually editing the ignore.conf file. Alternatively you can ignore files using the GUI as explained in the User Guide. Whether you end up using the GUI or editing the file, this blog post will help you understanding how the ignore rules work.
Why do you need to ignore files?
This is a familiar scenario that every developer can relate to. You have your workspace nicely set up and linked to its appropriate version control repository. All source files are checked in and organized.
But what happens after you build your project?
Lots of binary files will be created and the version control system will detect them as new!
You might experience the same issue with any other kind of non-permanent file such as IDE settings files, temporary files created while you are testing your code, and so on.
Obviously, you don't want to check in these files; it would mean you that have to review an unnecessarily long list of changes every time you want to check in source code modifications.
Or worse, if you decide to forget about these files and just check them in, your changesets will be cluttered with irrelevant information, making traceability more difficult and allowing errors to slip through.
But don't worry! This is where the Plastic SCM ignored items come into play.
What is an ignored file?
In Plastic SCM, an ignored item is just a private item that will not be added to the pending changes list unless explicitly told to do so. You accomplish this by placing rules inside a file called ignore.conf, located at the workspace root path. Each private item whose path is matched by one of those rules is ignored.
How ignored files work
To better understand how this works, let's have a look at an example.
If you use Microsoft Visual Studio as your IDE, binary files are placed by default at directories called bin and obj.
As we discussed above, you usually wish to prevent those files from being detected as private/new. It's as simple as adding the following lines to the ignore.conf file:
bin objThis means that any directory called bin or obj, along with all of their children, recursively, will be matched and therefore, excluded from the private objects list.
We can see the result in the next two figures.
In the first figure, there are almost 100 private files created by the compiler; they are the pending changes after the build:
Whereas once we add the rules, we just see some IDE settings files (and the ignore.conf file, of course!); they are the pending changes after the binary directories are configured to be ignored:
Advanced ignore rules
Naturally, the rule format is not limited to directory names. You can also choose to ignore all .suo files by just adding a new rule:
*.suo
This will remove the three remaining private files in our example (see next image), leaving our pending changes view with our ignore.conf file alone. Now, we would like it to be ignored too, but we don't want any other item to be affected. We just want to ignore that specific file, instead of every .conf file or every file called ignore.conf (we might have more in our workspace tree that we need to be included at some point). The appropriate rule is:
/ignore.conf
We can see the results in the next figure: the main ignore.conf has disappeared but some new .conf files haven't been ignored:
Also, we can decide to remove the AssemblyInfo.cs files from version control. We would just need to delete them in Plastic SCM and then add a line like this in our ignore.conf file:
AssemblyInfo.csPlease note that the rules are case sensitive, so we have to type them accordingly.
Exception rules
But we're not done yet! Plastic SCM supports exception rules, too. Exception rules are regular rules, preceded by the '!' symbol, that have the opposite effect; they force private items to be always present as new items. To illustrate this, let's say that there's a specific binary directory that we want to include if it appears. We only need to specify it as an exception rule:
!/LibGit2Sharp/bin
This will bring back the bin/ results directory of the LibGit2Sharp project.
Wildcard expansion
Both kinds of rules support wildcard expansion. For example: we wish to ignore all files and directories under directories called temp but we don't want .log files directly under them to be ignored. Implement thi behavior by using the following rules:
/sample/temp/** !/sample/temp/*.log
In the previous example, a ** string means "any character", whereas the single * character means "any character excluding path separators".
Learn more
If you want to learn more about some other configuration options, please read the following:
- Configure the hidden items that won't be displayed in the Pending changes view.
- Configure the cloaked files and directories that won't be downloaded during the update (or not updated if they were already on the workspace before being cloaked).
- Configure the items to keep as "readonly" after an update.
- Configure the items to keep as "writable" after an update.
Conclusion
So, that's it! In this post we've covered the different possibilities of ignoring private items that Plastic SCM offers, as well as some combinations of them. Feel free to experiment with your own workspace, and don't hesitate to share your thoughts in our forum!
How do you comment an ignore.conf file?
ReplyDeleteIt's important to know why something is being ignored...
Simple, just start the line with #.
Delete# this is a comment
:-)