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 d1567e5ea18500af85e894a73314957edc89c9ce..41f172b0900786e0d80296f2998f0a1e335e1b60 100644 (file)
--- 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 38ae8636739f9c24691a54f0e764413ada2f5f2b..794d47ce4b0da52732fe52e9ab82447d5ca99d18 100644 (file)
--- 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 8d044a81ec82c7dbb8fbfe6d5275ea42488a6c08..d74e906ee0e7fc850c5743ccbb0b01c84c0ce396 100644 (file)
--- 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 5041f54300c42de81867dad859dc1fa87e64b7ab..849d990ae85cd9aaccdf1d7782021498c6d07591 100644 (file)
--- 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 (file)
index 0000000..8c44c2c
--- /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 b53ff4e4fe7e15b9a306b9025e52b3a5829544c2..f07f6c2faef846c0edc4d64d62436e8fe299de60 100644 (file)
--- 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">