From: Andrej Shadura <andrew.shadura@collabora.co.uk>
Date: Sat, 13 Feb 2021 19:11:19 +0000 (+0100)
Subject: docs: Add a manpage for gbp setup-gitattributes
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=85b0b6599893dad34b57fba33f343b852dfadc59;p=tools%2Fgit-buildpackage.git

docs: Add a manpage for gbp setup-gitattributes

Describle how and why the attributes are being disabled, refer
to dgit, git-deborig and Git documentation; add a reference to
the gbp-clone manpage.

Signed-off-by: Andrej Shadura <andrew.shadura@collabora.co.uk>
---

diff --git a/docs/Makefile b/docs/Makefile
index d1567e5e..41f172b0 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -16,6 +16,7 @@ MAN1S = \
         gbp-pristine-tar  \
         gbp-pull          \
         gbp-push          \
+        gbp-setup-gitattributes \
         gbp-tag           \
         gbp-buildpackage-rpm \
         gbp-import-srpm   \
diff --git a/docs/common.ent b/docs/common.ent
index 38ae8636..794d47ce 100644
--- a/docs/common.ent
+++ b/docs/common.ent
@@ -35,6 +35,7 @@
   <!ENTITY gbp-pristine-tar	"<command>gbp&nbsp;pristine-tar</command>">
   <!ENTITY gbp-pull		"<command>gbp&nbsp;pull</command>">
   <!ENTITY gbp-push		"<command>gbp&nbsp;push</command>">
+  <!ENTITY gbp-setup-gitattributes "<command>gbp&nbsp;setup-gitattributes</command>">
   <!ENTITY gbp-rpm-ch           "<command>gbp rpm-ch</command>">
   <!ENTITY gbp-tag              "<command>gbp tag</command>">
   <!ENTITY gbp.conf		"<filename>gbp.conf</filename>">
diff --git a/docs/man.gbp.xml b/docs/man.gbp.xml
index 8d044a81..d74e906e 100644
--- a/docs/man.gbp.xml
+++ b/docs/man.gbp.xml
@@ -30,5 +30,6 @@
 &man.gbp.pull;
 &man.gbp.push;
 &man.gbp.rpm.ch;
+&man.gbp.setup.gitattributes;
 &man.gbp.tag;
 </reference>
diff --git a/docs/manpages/gbp-clone.xml b/docs/manpages/gbp-clone.xml
index 5041f543..849d990a 100644
--- a/docs/manpages/gbp-clone.xml
+++ b/docs/manpages/gbp-clone.xml
@@ -217,6 +217,7 @@
     <para>
       <xref linkend="man.gbp.buildpackage"/>,
       <xref linkend="man.gbp.pull"/>,
+      <xref linkend="man.gbp.setup.gitattributes"/>,
       <xref linkend="man.gbp.conf"/>,
       <citerefentry>
         <refentrytitle>gitattributes</refentrytitle>
diff --git a/docs/manpages/gbp-setup-gitattributes.xml b/docs/manpages/gbp-setup-gitattributes.xml
new file mode 100644
index 00000000..8c44c2ca
--- /dev/null
+++ b/docs/manpages/gbp-setup-gitattributes.xml
@@ -0,0 +1,77 @@
+<refentry id="man.gbp.setup.gitattributes">
+  <refentryinfo>
+    <address>
+      <email>andrew@shadura.me</email>
+    </address>
+    <author>
+      <firstname>Andrej</firstname>
+      <surname>Shadura</surname>
+    </author>
+  </refentryinfo>
+  <refmeta><refentrytitle>gbp-setup-gitattributes</refentrytitle>
+    &dhsection;
+  </refmeta>
+  <refnamediv>
+    <refname>gbp-setup-gitattributes</refname>
+    <refpurpose>Set up &git; attributes to disable transformations</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      &gbp-setup-gitattributes;
+
+      &man.common.options.synopsis;
+    </cmdsynopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>DESCRIPTION</title>
+    <para>
+      &gbp-setup-gitattributes; sets up <filename>.git/info/attributes</filename> in the current
+      repository to disable all transforming attributes for all files. This is done by defining
+      a macro attribute <symbol>[attr]dgit-defuse-attrs</symbol> and applying it to <filename>*</filename>
+      together with <symbol>export-subst</symbol> and <symbol>export-ignore</symbol>.
+    </para>
+    <para>
+      This method is compatible with <command>dgit</command> and <command>git-deborig</command>
+      which use this macro attribute. Older versions of <command>dgit</command> use an incomplete
+      preset missing some attributes; if such is found, it is replaced by an updated definition.
+    </para>
+    <para>
+      Disabling those attributes is necessary, since they cause often unwanted conversion of files
+      on checkout (e.g. line endings, encodings, etc). Working with such source tree is confusing,
+      since the working tree differs from the Git history (and sometimes from the source tarball),
+      and can lead to errors.
+    </para>
+    <para>
+      By default, &gbp-clone; tries to detect the usage of <filename>.gitattributes</filename> in the
+      upstream source and disable the Git attributes only when necessary.
+    </para>
+  </refsect1>
+  <refsect1>
+    <title>OPTIONS</title>
+    <variablelist>
+      &man.common.options.description;
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>SEE ALSO</title>
+    <para>
+      <xref linkend="man.gbp.clone"/>,
+      <xref linkend="man.gbp.push"/>,
+      <xref linkend="man.gbp.conf"/>,
+      <citerefentry>
+        <refentrytitle>gitattributes</refentrytitle>
+        <manvolnum>5</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>dgit</refentrytitle>
+        <manvolnum>7</manvolnum>
+      </citerefentry>
+    </para>
+  </refsect1>
+  <refsect1>
+    <title>AUTHOR</title>
+    <para>
+      Andrej Shadura <email>andrew@shadura.me</email>
+    </para>
+  </refsect1>
+</refentry>
diff --git a/docs/manpages/manpages.ent b/docs/manpages/manpages.ent
index b53ff4e4..f07f6c2f 100644
--- a/docs/manpages/manpages.ent
+++ b/docs/manpages/manpages.ent
@@ -19,6 +19,7 @@
 <!ENTITY man.gbp.pull SYSTEM "gbp-pull.xml">
 <!ENTITY man.gbp.push SYSTEM "gbp-push.xml">
 <!ENTITY man.gbp.rpm.ch SYSTEM "gbp-rpm-ch.xml">
+<!ENTITY man.gbp.setup.gitattributes SYSTEM "gbp-setup-gitattributes.xml">
 <!ENTITY man.gbp.tag SYSTEM "gbp-tag.xml">
 <!ENTITY man.seealso.common SYSTEM "man.seealso.xml">