From 1814af9f3444eea27412dc33dbb9a43f7666fd5b Mon Sep 17 00:00:00 2001
From: jfpanisset <32653482+jfpanisset@users.noreply.github.com>
Date: Thu, 1 Nov 2018 07:38:45 -0700
Subject: [PATCH] Document lineinfile regexp gotcha (#47912)

You typically want the lineinfile module to operate in an indempotent way, similar to using "sed -i", so your regexp needs to match the line to edit both before and after the edit, otherwise on a second run the regexp will no longer match the original text line and you will end up with a second copy of the replacement line at the top/bottom of the file.
---
 lib/ansible/modules/files/lineinfile.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/lib/ansible/modules/files/lineinfile.py b/lib/ansible/modules/files/lineinfile.py
index 00c45eb70a7..48b7409fe5a 100644
--- a/lib/ansible/modules/files/lineinfile.py
+++ b/lib/ansible/modules/files/lineinfile.py
@@ -48,6 +48,8 @@ options:
       - If the regular expression is not matched, the line will be
         added to the file in keeping with`insertbefore` or `insertafter`
         settings.
+      - When modifying a line the regexp should typically match both the initial state of
+        the line as well as its state after replacement by C(line) to ensure idempotence.
       - Uses Python regular expressions. See U(http://docs.python.org/2/library/re.html).
     version_added: '1.7'
   state: