Next Previous Contents

3. Usage

3.1 How to replace strings inside files

We will take an example to simplify the operation: We want to replace two strings inside all the *.htm files of the /home/fdupoux/ directory. The URL http://www.mygale.org/ had changed and became http://www.multimania.com/. Then we want to modifiy all the HTML files where this invalid URL appears, and update them. The second string to replace is dupoux@old-server.com which became fdupoux@new-server.org.

The two strings are:

First, you must create a new KFileReplace project. To do it, just run KFileReplace, or click on the File/New command. A dialog box asks you three things:

If you need to fix some criterias about the size and the date of the files to replace, check the Apply date or size criteria. Then you will have to complete a second dialog box.

Then, you have to add the two strings in the first list. To do it, click on Strings/Add string. In the dialog box, type the text you want to search ,and the text you want to replace with. In top, you must type http://www.mygale.org/, and in bottom http://www.multimania.com/. Click Ok to validate. You can add the second string to replace: dupoux@old-server.com with fdupoux@new-server.org. KFileReplace is able to replace multi-strings, chich are single or multi-lines. If you don't type any replace string, all the searched strings will be deleted of the files (replaced with nothing).

Now it's time to set the options you need. Please, read the next section to have informations about the options.

Now, to run the replace operation, click on File/Replace.

3.2 How to search for strings inside files

KFileReplace allows you to search strings inside files. This tools is more powerful than the standard kfind tool, because there are some advantages:

This operation is really near as the replace operations. Then we only will show the differences:

3.3 How to use wildcards in search and in replace string

Since version 0.5.1.0, KFileReplace support wildcards in the replace strings. Is is useful when you use wildcards in the search string, and you want the contents of the text wildcards are coding for to be inserted in the replace string. Then, you have to write, in the replace string, [#x#] where x is the number of the wildcard used.

The first number is 0, not 1 ! Then, [#0#] is the first wildcard used in the search string.

1) First example: - The search string is: LinuxWeb/*-*-*.html - The replace string is: LinuxWeb/[#0#]/[#1#].html ([#2#])

The following text:

LinuxWeb/Apache-index-19991213.html
LinuxWeb/Apache-config-19991218.html
LinuxWeb/Apache-server-19991221.html
LinuxWeb/NFS-index-19991213.html
LinuxWeb/NFS-config-19991213.html
LinuxWeb/Samba-index-19991213.html
LinuxWeb/Samba-config-19991213.html
LinuxWeb/Samba-hosts-19991213.html

In the first line: [#0#] = Apache [#1#] = index [#2#] = 19991213

Will become:

LinuxWeb/Apache/index.html (19991213)
LinuxWeb/Apache/config.html (19991218)
LinuxWeb/Apache/server.html (19991221)
LinuxWeb/NFS/index.html (19991213)
LinuxWeb/NFS/config.html (19991213)
LinuxWeb/Samba/index.html (19991213)
LinuxWeb/Samba/config.html (19991213)
LinuxWeb/Samba/hosts.html (19991213)

2) Second example: - The search string is: LinuxWeb/*-*-level?.html - The replace string is: LinuxWeb/[#0#]/[#1#] (type[#2#]).html

The following text:

LinuxWeb/Apache-index-LevelA.html
LinuxWeb/Apache-config- LevelB.html
LinuxWeb/Apache-server- LevelC.html
LinuxWeb/NFS-index- LevelA.html
LinuxWeb/NFS-config- LevelB.html
LinuxWeb/Samba-index- LevelA.html
LinuxWeb/Samba-config- LevelB.html
LinuxWeb/Samba-hosts- LevelC.html

Will become:

LinuxWeb/Apache/index (typeA).html
LinuxWeb/Apache/config (typeB).html
LinuxWeb/Apache/server (typeC).html
LinuxWeb/NFS/index (typeA).html
LinuxWeb/NFS/config (typeB).html
LinuxWeb/Samba/index (typeA).html
LinuxWeb/Samba/config (typeB).html
LinuxWeb/Samba/hosts (typeC).html

Here too, the first wildcard, and the second are expressions wildcards * and the last is a character wildcard ?. You need't use all search wildcards in the replace string. In the next example, the [#1#] wildcard is not used. You can also write twice a wildcard in the replace string (as [#0#] and [#2#])

3) Third example: - The search string is: LinuxWeb/*-*-level?.html - The replace string is: LinuxWeb/[#0#]/[#2#]/file.html ([#0#] in [#2#])

The following text:

LinuxWeb/Apache-index-LevelA.html
LinuxWeb/Apache-config- LevelB.html
LinuxWeb/Apache-server- LevelC.html
LinuxWeb/NFS-index- LevelA.html
LinuxWeb/NFS-config- LevelB.html
LinuxWeb/Samba-index- LevelA.html
LinuxWeb/Samba-config- LevelB.html
LinuxWeb/Samba-hosts- LevelC.html

Will become:

LinuxWeb/Apache/A/file.html (Apache in A)
LinuxWeb/Apache/B/file.html (Apache in B)
LinuxWeb/Apache/C/file.html (Apache in C)
LinuxWeb/NFS/A/file.html (NFS in A)
LinuxWeb/NFS/B/file.html (NFS in B)
LinuxWeb/Samba/A/file.html (Samba in A)
LinuxWeb/Samba/B/file.html (Samba in B)
LinuxWeb/Samba/C/file.html (Samba in C)

Before doing the replace operation, check the options are good. To do it, go in Options/Wildcards properties.... In the first two edit boxes, you can type what character will be the wildcards, instead of the default wildcards * for expressions, and ? for simple characters. And just after, you have a check box "USE WILDCARDS IN THE REPLACE STRINGS". You must check it, if you want to use wildcards in the two strings (search and replace) and to be able to do the same thing as the first and second example. You too have to check the general wildcard option is activated, by checking it in the Options menu.

3.4 How to use variables in a replace string

Since version 0.5.4.5, KFileReplace supports the variables. When doing the replace operation, the value of the variable is written. For example, you can use a datetime or a filename variable. The variable format is [$NAME:FORMAT$]. The name is the type of the variable: filename for the name of the file which is currently replaced, and datetime for the current date and time. The format gives more details about the style of the variable. For the filename, there is the full path of the file, the fullname with extension...

Example: When you replace TODAY in all *.html files, with the string The date is [$datetime:yyyy/mm/dd$] in the file [$filename:fullpath$], the result could be: The date is 1999/31/12 in the file /home/fdupoux/web/index.html

The following variables and formats are supported:

datetime: current date and time

filename name or path of the currently replaced file. Ex: "/home/fdupoux/kfilereplace.htm"

filelwtime Last Write time/date of the currently replaced file.

filelrtime Last Read time/date of the currently replaced file.

filesize Size of the currently replaced file.

owner Owner user and group of the currently replaced file.

3.5 How to use kfilereplace with the command line

KFileReplace is a KDE application, but it can be used with the command line. It can be useful when doing the same operation a lot of times. Then you just have to type a command, which can be used a lot of times. To see options, just type kfilereplace --help.

You can use the command mode to open a new project without having the "New Project" Dialog. To fo it, you must type the two parameters: the directory of the operation, and the type of the files to search for. For example, you can open a new project with the following command: kfilereplace /home/fdupoux/website/ *.html;*.xml.

You also can use the command line mode to make a search or a remplace operation. Then you can need to have strings. To open strings, you must have some strings saved in a KFR file. To open the file, you must add it on the command line: -l file.kfr. Then, you have to type the type of operation to do (search or replace).

For example, to replace all the strings which are in /home/me/strings.kfr, in the /home/me/website directory, in all *.html files, type: kfilereplace --replace -l /home/me/strings.kfr /home/me/website *.html. If you can to close KFileReplace after the operation, just add --exit to the command line.

3.6 How to restore a file (undo a replace operation)

KFileReplace can replace strings inside files. Then, files are modified. In some cases, if there are bugs, or if you make mistakes, you will need to restore files as they were before the replace operation. There are more ways to undo it:

First, you can make the opposite operation. If you replaced two strings: A1 with A2 and B1 with B2, you can restore by replacing B2 with B1, and A2 with A1. You can do it easily by using the strings/invert all strings command. For example, if you have replaced www.kde.org/index.html with www.kde.com/, to resolve the problem, you can replace www.kde.com/ with www.kde.org/index.html.

But it can be impossible in some cases:

There is another solution to restore original files. If the create backup option was not disabled, all original files were copied into an .old file before changes were made. Then, you can delete files, and rename all old files into original files.


Next Previous Contents