1@c This file is part of the GNU gettext manual. 2@c Copyright (C) 1995-2019 Free Software Foundation, Inc. 3@c See the file gettext.texi for copying conditions. 4 5@pindex msggrep 6@cindex @code{msggrep} program, usage 7@example 8msggrep [@var{option}] [@var{inputfile}] 9@end example 10 11@cindex search messages in a catalog 12The @code{msggrep} program extracts all messages of a translation catalog 13that match a given pattern or belong to some given source files. 14 15@subsection Input file location 16 17@table @samp 18@item @var{inputfile} 19Input PO file. 20 21@item -D @var{directory} 22@itemx --directory=@var{directory} 23@opindex -D@r{, @code{msggrep} option} 24@opindex --directory@r{, @code{msggrep} option} 25Add @var{directory} to the list of directories. Source files are 26searched relative to this list of directories. The resulting @file{.po} 27file will be written relative to the current directory, though. 28 29@end table 30 31If no @var{inputfile} is given or if it is @samp{-}, standard input is read. 32 33@subsection Output file location 34 35@table @samp 36@item -o @var{file} 37@itemx --output-file=@var{file} 38@opindex -o@r{, @code{msggrep} option} 39@opindex --output-file@r{, @code{msggrep} option} 40Write output to specified file. 41 42@end table 43 44The results are written to standard output if no output file is specified 45or if it is @samp{-}. 46 47@subsection Message selection 48 49@example 50 [-N @var{sourcefile}]... [-M @var{domainname}]... 51 [-J @var{msgctxt-pattern}] [-K @var{msgid-pattern}] [-T @var{msgstr-pattern}] 52 [-C @var{comment-pattern}] 53@end example 54 55A message is selected if 56@itemize @bullet 57@item it comes from one of the specified source files, 58@item or if it comes from one of the specified domains, 59@item or if @samp{-J} is given and its context (msgctxt) matches 60@var{msgctxt-pattern}, 61@item or if @samp{-K} is given and its key (msgid or msgid_plural) matches 62@var{msgid-pattern}, 63@item or if @samp{-T} is given and its translation (msgstr) matches 64@var{msgstr-pattern}, 65@item or if @samp{-C} is given and the translator's comment matches 66@var{comment-pattern}. 67@end itemize 68 69When more than one selection criterion is specified, the set of selected 70messages is the union of the selected messages of each criterion. 71 72@var{msgctxt-pattern} or @var{msgid-pattern} or @var{msgstr-pattern} syntax: 73@example 74 [-E | -F] [-e @var{pattern} | -f @var{file}]... 75@end example 76@var{pattern}s are basic regular expressions by default, or extended regular 77expressions if -E is given, or fixed strings if -F is given. 78 79@table @samp 80@item -N @var{sourcefile} 81@itemx --location=@var{sourcefile} 82@opindex -N@r{, @code{msggrep} option} 83@opindex --location@r{, @code{msggrep} option} 84Select messages extracted from @var{sourcefile}. @var{sourcefile} can be 85either a literal file name or a wildcard pattern. 86 87@item -M @var{domainname} 88@itemx --domain=@var{domainname} 89@opindex -M@r{, @code{msggrep} option} 90@opindex --domain@r{, @code{msggrep} option} 91Select messages belonging to domain @var{domainname}. 92 93@item -J 94@itemx --msgctxt 95@opindex -J@r{, @code{msggrep} option} 96@opindex --msgctxt@r{, @code{msggrep} option} 97Start of patterns for the msgctxt. 98 99@item -K 100@itemx --msgid 101@opindex -K@r{, @code{msggrep} option} 102@opindex --msgid@r{, @code{msggrep} option} 103Start of patterns for the msgid. 104 105@item -T 106@itemx --msgstr 107@opindex -T@r{, @code{msggrep} option} 108@opindex --msgstr@r{, @code{msggrep} option} 109Start of patterns for the msgstr. 110 111@item -C 112@itemx --comment 113@opindex -C@r{, @code{msggrep} option} 114@opindex --comment@r{, @code{msggrep} option} 115Start of patterns for the translator's comment. 116 117@item -X 118@itemx --extracted-comment 119@opindex -X@r{, @code{msggrep} option} 120@opindex --extracted-comment@r{, @code{msggrep} option} 121Start of patterns for the extracted comments. 122 123@item -E 124@itemx --extended-regexp 125@opindex -E@r{, @code{msggrep} option} 126@opindex --extended-regexp@r{, @code{msggrep} option} 127Specify that @var{pattern} is an extended regular expression. 128 129@item -F 130@itemx --fixed-strings 131@opindex -F@r{, @code{msggrep} option} 132@opindex --fixed-strings@r{, @code{msggrep} option} 133Specify that @var{pattern} is a set of newline-separated strings. 134 135@item -e @var{pattern} 136@itemx --regexp=@var{pattern} 137@opindex -e@r{, @code{msggrep} option} 138@opindex --regexp=@r{, @code{msggrep} option} 139Use @var{pattern} as a regular expression. 140 141@item -f @var{file} 142@itemx --file=@var{file} 143@opindex -f@r{, @code{msggrep} option} 144@opindex --file@r{, @code{msggrep} option} 145Obtain @var{pattern} from @var{file}. 146 147@item -i 148@itemx --ignore-case 149@opindex -i@r{, @code{msggrep} option} 150@opindex --ignore-case@r{, @code{msggrep} option} 151Ignore case distinctions. 152 153@item -v 154@itemx --invert-match 155@opindex -v@r{, @code{msggrep} option} 156@opindex --invert-match@r{, @code{msggrep} option} 157Output only the messages that do not match any selection criterion, instead 158of the messages that match a selection criterion. 159 160@end table 161 162@subsection Input file syntax 163 164@table @samp 165@item -P 166@itemx --properties-input 167@opindex -P@r{, @code{msggrep} option} 168@opindex --properties-input@r{, @code{msggrep} option} 169Assume the input file is a Java ResourceBundle in Java @code{.properties} 170syntax, not in PO file syntax. 171 172@item --stringtable-input 173@opindex --stringtable-input@r{, @code{msggrep} option} 174Assume the input file is a NeXTstep/GNUstep localized resource file in 175@code{.strings} syntax, not in PO file syntax. 176 177@end table 178 179@subsection Output details 180 181@c --no-escape and --escape omitted on purpose. They are not useful. 182 183@table @samp 184@item --color 185@itemx --color=@var{when} 186@opindex --color@r{, @code{msggrep} option} 187Specify whether or when to use colors and other text attributes. 188See @ref{The --color option} for details. 189 190@item --style=@var{style_file} 191@opindex --style@r{, @code{msggrep} option} 192Specify the CSS style rule file to use for @code{--color}. 193See @ref{The --style option} for details. 194 195@item --force-po 196@opindex --force-po@r{, @code{msggrep} option} 197Always write an output file even if it contains no message. 198 199@item --indent 200@opindex --indent@r{, @code{msggrep} option} 201Write the .po file using indented style. 202 203@item --no-location 204@opindex --no-location@r{, @code{msggrep} option} 205Do not write @samp{#: @var{filename}:@var{line}} lines. 206 207@item -n 208@itemx --add-location=@var{type} 209@opindex --add-location@r{, @code{msggrep} option} 210Generate @samp{#: @var{filename}:@var{line}} lines (default). 211 212The optional @var{type} can be either @samp{full}, @samp{file}, or 213@samp{never}. If it is not given or @samp{full}, it generates the 214lines with both file name and line number. If it is @samp{file}, the 215line number part is omitted. If it is @samp{never}, it completely 216suppresses the lines (same as @code{--no-location}). 217 218@item --strict 219@opindex --strict@r{, @code{msggrep} option} 220Write out a strict Uniforum conforming PO file. Note that this 221Uniforum format should be avoided because it doesn't support the 222GNU extensions. 223 224@item -p 225@itemx --properties-output 226@opindex -p@r{, @code{msggrep} option} 227@opindex --properties-output@r{, @code{msggrep} option} 228Write out a Java ResourceBundle in Java @code{.properties} syntax. Note 229that this file format doesn't support plural forms and silently drops 230obsolete messages. 231 232@item --stringtable-output 233@opindex --stringtable-output@r{, @code{msggrep} option} 234Write out a NeXTstep/GNUstep localized resource file in @code{.strings} syntax. 235Note that this file format doesn't support plural forms. 236 237@item -w @var{number} 238@itemx --width=@var{number} 239@opindex -w@r{, @code{msggrep} option} 240@opindex --width@r{, @code{msggrep} option} 241Set the output page width. Long strings in the output files will be 242split across multiple lines in order to ensure that each line's width 243(= number of screen columns) is less or equal to the given @var{number}. 244 245@item --no-wrap 246@opindex --no-wrap@r{, @code{msggrep} option} 247Do not break long message lines. Message lines whose width exceeds the 248output page width will not be split into several lines. Only file reference 249lines which are wider than the output page width will be split. 250 251@item --sort-output 252@opindex --sort-output@r{, @code{msggrep} option} 253Generate sorted output. Note that using this option makes it much harder 254for the translator to understand each message's context. 255 256@item --sort-by-file 257@opindex --sort-by-file@r{, @code{msggrep} option} 258Sort output by file location. 259 260@end table 261 262@subsection Informative output 263 264@table @samp 265@item -h 266@itemx --help 267@opindex -h@r{, @code{msggrep} option} 268@opindex --help@r{, @code{msggrep} option} 269Display this help and exit. 270 271@item -V 272@itemx --version 273@opindex -V@r{, @code{msggrep} option} 274@opindex --version@r{, @code{msggrep} option} 275Output version information and exit. 276 277@end table 278 279@subsection Examples 280 281To extract the messages that come from the source files 282@code{gnulib-lib/error.c} and @code{gnulib-lib/getopt.c}: 283 284@smallexample 285msggrep -N gnulib-lib/error.c -N gnulib-lib/getopt.c input.po 286@end smallexample 287 288To extract the messages that contain the string ``Please specify'' in the 289original string: 290 291@smallexample 292msggrep --msgid -F -e 'Please specify' input.po 293@end smallexample 294 295To extract the messages that have a context specifier of either ``Menu>File'' 296or ``Menu>Edit'' or a submenu of them: 297 298@smallexample 299msggrep --msgctxt -E -e '^Menu>(File|Edit)' input.po 300@end smallexample 301 302To extract the messages whose translation contains one of the strings in the 303file @code{wordlist.txt}: 304 305@smallexample 306msggrep --msgstr -F -f wordlist.txt input.po 307@end smallexample 308