community.windows.win_lineinfile 模块 – 确保特定行存在于文件中，或使用反向引用正则表达式替换现有行

注意

此模块是 community.windows 集合 (版本 2.3.0) 的一部分。

如果您使用的是 ansible 包，则可能已安装此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用： ansible-galaxy collection install community.windows。

要在 playbook 中使用它，请指定： community.windows.win_lineinfile。

概要 

此模块将搜索文件中的行，并确保它存在或不存在。
这主要用于您只想更改文件中的一行的情况。

参数 

参数	注释
backrefs 布尔值	与 `state=present` 一起使用。如果设置，行可以包含反向引用（位置引用和命名引用），如果 `regexp` 匹配，则这些引用将被填充。此标志会稍微改变模块的操作；`insertbefore` 和 `insertafter` 将被忽略，如果 `regexp` 在文件中任何位置都不匹配，则文件将保持不变。如果 `regexp` 匹配，则最后匹配的行将被扩展的行参数替换。选项 `false` ← (默认) `true`
backup 布尔值	确定是否应创建备份。设置为 `yes` 时，将创建一个包含时间戳信息的备份文件，以便您可以找回原始文件（如果您不小心将其弄乱了）。选项 `false` ← (默认) `true`
create 布尔值	与 `state=present` 一起使用。如果指定，则如果文件尚不存在，则将创建该文件。默认情况下，如果文件丢失，它将失败。选项 `false` ← (默认) `true`
encoding 字符串	指定要操作的源文本文件的编码（以及输出编码）。`auto` 的默认值将使模块自动检测源文件的编码，并确保以相同的编码写入修改后的文件。可以将显式编码作为字符串传递，该字符串是有效值，可以传递给 .NET framework System.Text.Encoding.GetEncoding() 方法 - 请参见 https://msdn.microsoft.com/en-us/library/system.text.encoding%28v=vs.110%29.aspx。这主要在 `create=yes` 时有用，如果您想创建一个具有特定编码的新文件。如果指定了 `create=yes` 但没有特定编码，则将使用默认编码（UTF-8，无 BOM）。默认值： `"auto"`
insertafter 字符串	与 `state=present` 一起使用。如果指定，则该行将插入到指定正则表达式的最后一次匹配之后。可以使用一个特殊值；`EOF` 用于将行插入到文件的末尾。如果指定的正则表达式没有匹配项，则将使用 EOF。不能与 `backrefs` 一起使用。选项 `"EOF"` ← (默认) `"regex"`
insertbefore 字符串	与 `state=present` 一起使用。如果指定，则该行将插入到指定正则表达式的最后一次匹配之前。可以使用一个值；`BOF` 用于将行插入到文件的开头。如果指定的正则表达式没有匹配项，则该行将插入到文件的末尾。不能与 `backrefs` 一起使用。选项 `"BOF"` `"regex"`
line 字符串	对于 `state=present` 是必需的。要插入/替换到文件中的行。如果设置了 `backrefs`，则可以包含反向引用，如果正则表达式匹配，则这些反向引用将使用 `regexp` 捕获组进行扩展。请注意，该行首先在控制器上进行处理，因此依赖于 yaml 引号规则。任何双引号的行都将扩展控制字符，例如“\r\n”。要逐字打印此类字符，请使用单引号或不使用引号。
newline 字符串	指定修改后的文件使用的换行符样式。默认值为 Windows 换行符 (`\r\n`)。请注意，无论输入文件中原始换行符是什么，输出文件都将使用指定的换行符。选项 `“unix”` `"windows"` ← (默认)
路径别名：dest, destfile, name 路径 / 必填	要修改的文件的路径。请注意，当行使用双引号括起来时，Windows 路径分隔符 `\` 必须转义为 `\\`。
正则表达式别名：regexp 字符串	在文件的每一行中查找的正则表达式。对于 `state=present`，如果找到则替换的模式；只替换找到的最后一行。对于 `state=absent`，要移除的行的模式。使用与 .NET 兼容的正则表达式；参见 https://msdn.microsoft.com/en-us/library/hs600312%28v=vs.110%29.aspx。
状态字符串	该行是否存在。选项 `“absent”` `"present"` ← (默认)
验证字符串	在复制到目标位置之前运行的验证。在命令中使用 %s 来指示要验证的当前文件。命令以安全方式传递，因此 shell 功能（如扩展和管道）将无法使用。

另请参见 

另请参见

ansible.builtin.assemble: 从片段组装配置文件。
ansible.builtin.lineinfile: 管理文本文件中的行。

示例 

- name: Insert path without converting \r\n
  community.windows.win_lineinfile:
    path: c:\file.txt
    line: c:\return\new

- community.windows.win_lineinfile:
    path: C:\Temp\example.conf
    regex: '^name='
    line: 'name=JohnDoe'

- community.windows.win_lineinfile:
    path: C:\Temp\example.conf
    regex: '^name='
    state: absent

- community.windows.win_lineinfile:
    path: C:\Temp\example.conf
    regex: '^127\.0\.0\.1'
    line: '127.0.0.1 localhost'

- community.windows.win_lineinfile:
    path: C:\Temp\httpd.conf
    regex: '^Listen '
    insertafter: '^#Listen '
    line: Listen 8080

- community.windows.win_lineinfile:
    path: C:\Temp\services
    regex: '^# port for http'
    insertbefore: '^www.*80/tcp'
    line: '# port for http by default'

- name: Create file if it doesn't exist with a specific encoding
  community.windows.win_lineinfile:
    path: C:\Temp\utf16.txt
    create: true
    encoding: utf-16
    line: This is a utf-16 encoded file

- name: Add a line to a file and ensure the resulting file uses unix line separators
  community.windows.win_lineinfile:
    path: C:\Temp\testfile.txt
    line: Line added to file
    newline: unix

- name: Update a line using backrefs
  community.windows.win_lineinfile:
    path: C:\Temp\example.conf
    backrefs: true
    regex: '(^name=)'
    line: '$1JohnDoe'

返回值 

常用返回值已在此处记录，以下是此模块特有的字段

键	描述
backup 字符串	已创建的备份文件的名称。此字段现已弃用，请改用 `backup_file`。返回值：如果 backup=yes 示例： `"C:\\Path\\To\\File.txt.11540.20150212-220915.bak"`
backup_file 字符串	已创建的备份文件的名称。返回值：如果 backup=yes 示例： `"C:\\Path\\To\\File.txt.11540.20150212-220915.bak"`

作者

Brian Lloyd (@brianlloyd)

参数	注释
backrefs 布尔值	与 `state=present` 一起使用。如果设置，行可以包含反向引用（位置引用和命名引用），如果 `regexp` 匹配，则这些引用将被填充。此标志会稍微改变模块的操作；`insertbefore` 和 `insertafter` 将被忽略，如果 `regexp` 在文件中任何位置都不匹配，则文件将保持不变。如果 `regexp` 匹配，则最后匹配的行将被扩展的行参数替换。选项 `false` ← (默认) `true`
backup 布尔值	确定是否应创建备份。设置为 `yes` 时，将创建一个包含时间戳信息的备份文件，以便您可以找回原始文件（如果您不小心将其弄乱了）。选项 `false` ← (默认) `true`
create 布尔值	与 `state=present` 一起使用。如果指定，则如果文件尚不存在，则将创建该文件。默认情况下，如果文件丢失，它将失败。选项 `false` ← (默认) `true`
encoding 字符串	指定要操作的源文本文件的编码（以及输出编码）。`auto` 的默认值将使模块自动检测源文件的编码，并确保以相同的编码写入修改后的文件。可以将显式编码作为字符串传递，该字符串是有效值，可以传递给 .NET framework System.Text.Encoding.GetEncoding() 方法 - 请参见 https://msdn.microsoft.com/en-us/library/system.text.encoding%28v=vs.110%29.aspx。这主要在 `create=yes` 时有用，如果您想创建一个具有特定编码的新文件。如果指定了 `create=yes` 但没有特定编码，则将使用默认编码（UTF-8，无 BOM）。默认值： `"auto"`
insertafter 字符串	与 `state=present` 一起使用。如果指定，则该行将插入到指定正则表达式的最后一次匹配之后。可以使用一个特殊值；`EOF` 用于将行插入到文件的末尾。如果指定的正则表达式没有匹配项，则将使用 EOF。不能与 `backrefs` 一起使用。选项 `"EOF"` ← (默认) `"regex"`
insertbefore 字符串	与 `state=present` 一起使用。如果指定，则该行将插入到指定正则表达式的最后一次匹配之前。可以使用一个值；`BOF` 用于将行插入到文件的开头。如果指定的正则表达式没有匹配项，则该行将插入到文件的末尾。不能与 `backrefs` 一起使用。选项 `"BOF"` `"regex"`
line 字符串	对于 `state=present` 是必需的。要插入/替换到文件中的行。如果设置了 `backrefs`，则可以包含反向引用，如果正则表达式匹配，则这些反向引用将使用 `regexp` 捕获组进行扩展。请注意，该行首先在控制器上进行处理，因此依赖于 yaml 引号规则。任何双引号的行都将扩展控制字符，例如“\r\n”。要逐字打印此类字符，请使用单引号或不使用引号。
newline 字符串	指定修改后的文件使用的换行符样式。默认值为 Windows 换行符 (`\r\n`)。请注意，无论输入文件中原始换行符是什么，输出文件都将使用指定的换行符。选项 `“unix”` `"windows"` ← (默认)
路径别名：dest, destfile, name 路径 / 必填	要修改的文件的路径。请注意，当行使用双引号括起来时，Windows 路径分隔符 `\` 必须转义为 `\\`。
正则表达式别名：regexp 字符串	在文件的每一行中查找的正则表达式。对于 `state=present`，如果找到则替换的模式；只替换找到的最后一行。对于 `state=absent`，要移除的行的模式。使用与 .NET 兼容的正则表达式；参见 https://msdn.microsoft.com/en-us/library/hs600312%28v=vs.110%29.aspx。
状态字符串	该行是否存在。选项 `“absent”` `"present"` ← (默认)
验证字符串	在复制到目标位置之前运行的验证。在命令中使用 %s 来指示要验证的当前文件。命令以安全方式传递，因此 shell 功能（如扩展和管道）将无法使用。