about summary refs log tree commit diff
path: root/third_party/git/contrib/hooks/multimail/doc
diff options
context:
space:
mode:
authorVincent Ambo <mail@tazj.in>2021-09-21T10·03+0300
committerVincent Ambo <mail@tazj.in>2021-09-21T11·29+0300
commit43b1791ec601732ac31195df96781a848360a9ac (patch)
treedaae8d638343295d2f1f7da955e556ef4c958864 /third_party/git/contrib/hooks/multimail/doc
parent2d8e7dc9d9c38127ec4ebd13aee8e8f586a43318 (diff)
chore(3p/git): Unvendor git and track patches instead r/2903
This was vendored a long time ago under the expectation that keeping
it in sync with cgit would be easier this way, but it has proven not
to be a big issue.

On the other hand, a vendored copy of git is an annoying maintenance
burden. It is much easier to rebase the single (dottime) patch that we
have.

This removes the vendored copy of git and instead passes the git
source code to cgit via `pkgs.srcOnly`, which includes the applied
patch so that cgit can continue rendering dottime.

Change-Id: If31f62dea7ce688fd1b9050204e9378019775f2b
Diffstat (limited to 'third_party/git/contrib/hooks/multimail/doc')
-rw-r--r--third_party/git/contrib/hooks/multimail/doc/customizing-emails.rst56
-rw-r--r--third_party/git/contrib/hooks/multimail/doc/gerrit.rst56
-rw-r--r--third_party/git/contrib/hooks/multimail/doc/gitolite.rst118
-rw-r--r--third_party/git/contrib/hooks/multimail/doc/troubleshooting.rst78
4 files changed, 0 insertions, 308 deletions
diff --git a/third_party/git/contrib/hooks/multimail/doc/customizing-emails.rst b/third_party/git/contrib/hooks/multimail/doc/customizing-emails.rst
deleted file mode 100644
index 3f5b67f768db..000000000000
--- a/third_party/git/contrib/hooks/multimail/doc/customizing-emails.rst
+++ /dev/null
@@ -1,56 +0,0 @@
-Customizing the content and formatting of emails
-================================================
-
-Overloading template strings
-----------------------------
-
-The content of emails is generated based on template strings defined
-in ``git_multimail.py``. You can customize these template strings
-without changing the script itself, by defining a Python wrapper
-around it. The python wrapper should ``import git_multimail`` and then
-override the ``git_multimail.*`` strings like this::
-
-  import sys  # needed for sys.argv
-
-  # Import and customize git_multimail:
-  import git_multimail
-  git_multimail.REVISION_INTRO_TEMPLATE = """..."""
-  git_multimail.COMBINED_INTRO_TEMPLATE = git_multimail.REVISION_INTRO_TEMPLATE
-
-  # start git_multimail itself:
-  git_multimail.main(sys.argv[1:])
-
-The template strings can use any value already used in the existing
-templates (read the source code).
-
-Using HTML in template strings
-------------------------------
-
-If ``multimailhook.commitEmailFormat`` is set to HTML, then
-git-multimail will generate HTML emails for commit notifications. The
-log and diff will be formatted automatically by git-multimail. By
-default, any HTML special character in the templates will be escaped.
-
-To use HTML formatting in the introduction of the email, set
-``multimailhook.htmlInIntro`` to ``true``. Then, the template can
-contain any HTML tags, that will be sent as-is in the email. For
-example, to add some formatting and a link to the online commit, use
-a format like::
-
-  git_multimail.REVISION_INTRO_TEMPLATE = """\
-  <span style="color:#808080">This is an automated email from the git hooks/post-receive script.</span><br /><br />
-
-  <strong>%(pusher)s</strong> pushed a commit to %(refname_type)s %(short_refname)s
-  in repository %(repo_shortname)s.<br />
-
-  <a href="https://github.com/git-multimail/git-multimail/commit/%(newrev)s">View on GitHub</a>.
-  """
-
-Note that the values expanded from ``%(variable)s`` in the format
-strings will still be escaped.
-
-For a less flexible but easier to set up way to add a link to commit
-emails, see ``multimailhook.commitBrowseURL``.
-
-Similarly, one can set ``multimailhook.htmlInFooter`` and override any
-of the ``*_FOOTER*`` template strings.
diff --git a/third_party/git/contrib/hooks/multimail/doc/gerrit.rst b/third_party/git/contrib/hooks/multimail/doc/gerrit.rst
deleted file mode 100644
index 8011d05dec03..000000000000
--- a/third_party/git/contrib/hooks/multimail/doc/gerrit.rst
+++ /dev/null
@@ -1,56 +0,0 @@
-Setting up git-multimail on Gerrit
-==================================
-
-Gerrit has its own email-sending system, but you may prefer using
-``git-multimail`` instead. It supports Gerrit natively as a Gerrit
-``ref-updated`` hook (Warning: `Gerrit hooks
-<https://gerrit-review.googlesource.com/Documentation/config-hooks.html>`__
-are distinct from Git hooks). Setting up ``git-multimail`` on a Gerrit
-installation can be done following the instructions below.
-
-The explanations show an easy way to set up ``git-multimail``,
-but leave ``git-multimail`` installed and unconfigured for a while. If
-you run Gerrit on a production server, it is advised that you
-execute the step "Set up the hook" last to avoid confusing your users
-in the meantime.
-
-Set up the hook
----------------
-
-Create a directory ``$site_path/hooks/`` if it does not exist (if you
-don't know what ``$site_path`` is, run ``gerrit.sh status`` and look
-for a ``GERRIT_SITE`` line). Either copy ``git_multimail.py`` to
-``$site_path/hooks/ref-updated`` or create a wrapper script like
-this::
-
-  #! /bin/sh
-  exec /path/to/git_multimail.py "$@"
-
-In both cases, make sure the file is named exactly
-``$site_path/hooks/ref-updated`` and is executable.
-
-(Alternatively, you may configure the ``[hooks]`` section of
-gerrit.config)
-
-Configuration
--------------
-
-Log on the gerrit server and edit ``$site_path/git/$project/config``
-to configure ``git-multimail``.
-
-Troubleshooting
----------------
-
-Warning: this will disable ``git-multimail`` during the debug, and
-could confuse your users. Don't run on a production server.
-
-To debug configuration issues with ``git-multimail``, you can add the
-``--stdout`` option when calling ``git_multimail.py`` like this::
-
-  #!/bin/sh
-  exec /path/to/git-multimail/git-multimail/git_multimail.py \
-    --stdout "$@" >> /tmp/log.txt
-
-and try pushing from a test repository. You should see the source of
-the email that would have been sent in the output of ``git push`` in
-the file ``/tmp/log.txt``.
diff --git a/third_party/git/contrib/hooks/multimail/doc/gitolite.rst b/third_party/git/contrib/hooks/multimail/doc/gitolite.rst
deleted file mode 100644
index 505483310552..000000000000
--- a/third_party/git/contrib/hooks/multimail/doc/gitolite.rst
+++ /dev/null
@@ -1,118 +0,0 @@
-Setting up git-multimail on gitolite
-====================================
-
-``git-multimail`` supports gitolite 3 natively.
-The explanations below show an easy way to set up ``git-multimail``,
-but leave ``git-multimail`` installed and unconfigured for a while. If
-you run gitolite on a production server, it is advised that you
-execute the step "Set up the hook" last to avoid confusing your users
-in the meantime.
-
-Set up the hook
----------------
-
-Log in as your gitolite user.
-
-Create a file ``.gitolite/hooks/common/post-receive`` on your gitolite
-account containing (adapt the path, obviously)::
-
-  #!/bin/sh
-  exec /path/to/git-multimail/git-multimail/git_multimail.py "$@"
-
-Make sure it's executable (``chmod +x``). Record the hook in
-gitolite::
-
-  gitolite setup
-
-Configuration
--------------
-
-First, you have to allow the admin to set Git configuration variables.
-
-As gitolite user, edit the line containing ``GIT_CONFIG_KEYS`` in file
-``.gitolite.rc``, to make it look like::
-
-  GIT_CONFIG_KEYS                 =>  'multimailhook\..*',
-
-You can now log out and return to your normal user.
-
-In the ``gitolite-admin`` clone, edit the file ``conf/gitolite.conf``
-and add::
-
-  repo @all
-      # Not strictly needed as git_multimail.py will chose gitolite if
-      # $GL_USER is set.
-      config multimailhook.environment = gitolite
-      config multimailhook.mailingList = # Where emails should be sent
-      config multimailhook.from = # From address to use
-
-Note that by default, gitolite forbids ``<`` and ``>`` in variable
-values (for security/paranoia reasons, see
-`compensating for UNSAFE_PATT
-<http://gitolite.com/gitolite/git-config/index.html#compensating-for-unsafe95patt>`__
-in gitolite's documentation for explanations and a way to disable
-this). As a consequence, you will not be able to use ``First Last
-<First.Last@example.com>`` as recipient email, but specifying
-``First.Last@example.com`` alone works.
-
-Obviously, you can customize all parameters on a per-repository basis by
-adding these ``config multimailhook.*`` lines in the section
-corresponding to a repository or set of repositories.
-
-To activate ``git-multimail`` on a per-repository basis, do not set
-``multimailhook.mailingList`` in the ``@all`` section and set it only
-for repositories for which you want ``git-multimail``.
-
-Alternatively, you can set up the ``From:`` field on a per-user basis
-by adding a ``BEGIN USER EMAILS``/``END USER EMAILS`` section (see
-``../README``).
-
-Specificities of Gitolite for Configuration
--------------------------------------------
-
-Empty configuration variables
-.............................
-
-With gitolite, the syntax ``config multimailhook.commitList = ""``
-unsets the variable instead of setting it to an empty string (see
-`here
-<http://gitolite.com/gitolite/git-config.html#an-important-warning-about-deleting-a-config-line>`__).
-As a result, there is no way to set a variable to the empty string.
-In all most places where an empty value is required, git-multimail
-now allows to specify special ``"none"`` value (case-sensitive) to
-mean the same.
-
-Alternatively, one can use ``" "`` (a single space) instead of ``""``.
-In most cases (in particular ``multimailhook.*List`` variables), this
-will be equivalent to an empty string.
-
-If you have a use-case where ``"none"`` is not an acceptable value and
-you need ``" "`` or  ``""`` instead, please report it as a bug to
-git-multimail.
-
-Allowing Regular Expressions in Configuration
-.............................................
-
-gitolite has a mechanism to prevent unsafe configuration variable
-values, which prevent characters like ``|`` commonly used in regular
-expressions. If you do not need the safety feature of gitolite and
-need to use regular expressions in your configuration (e.g. for
-``multimailhook.refFilter*`` variables), set
-`UNSAFE_PATT
-<http://gitolite.com/gitolite/git-config.html#unsafe-patt>`__ to a
-less restrictive value.
-
-Troubleshooting
----------------
-
-Warning: this will disable ``git-multimail`` during the debug, and
-could confuse your users. Don't run on a production server.
-
-To debug configuration issues with ``git-multimail``, you can add the
-``--stdout`` option when calling ``git_multimail.py`` like this::
-
-  #!/bin/sh
-  exec /path/to/git-multimail/git-multimail/git_multimail.py --stdout "$@"
-
-and try pushing from a test repository. You should see the source of
-the email that would have been sent in the output of ``git push``.
diff --git a/third_party/git/contrib/hooks/multimail/doc/troubleshooting.rst b/third_party/git/contrib/hooks/multimail/doc/troubleshooting.rst
deleted file mode 100644
index 651b509ee66c..000000000000
--- a/third_party/git/contrib/hooks/multimail/doc/troubleshooting.rst
+++ /dev/null
@@ -1,78 +0,0 @@
-Troubleshooting issues with git-multimail: a FAQ
-================================================
-
-How to check that git-multimail is properly set up?
----------------------------------------------------
-
-Since version 1.4.0, git-multimail allows a simple self-checking of
-its configuration: run it with the environment variable
-``GIT_MULTIMAIL_CHECK_SETUP`` set to a non-empty string. You should
-get something like this::
-
-  $ GIT_MULTIMAIL_CHECK_SETUP=true /home/moy/dev/git-multimail/git-multimail/git_multimail.py
-  Environment values:
-      administrator : 'the administrator of this repository'
-      charset : 'utf-8'
-      emailprefix : '[git-multimail] '
-      fqdn : 'anie'
-      projectdesc : 'UNNAMED PROJECT'
-      pusher : 'moy'
-      repo_path : '/home/moy/dev/git-multimail'
-      repo_shortname : 'git-multimail'
-
-  Now, checking that git-multimail's standard input is properly set ...
-  Please type some text and then press Return
-  foo
-  You have just entered:
-  foo
-  git-multimail seems properly set up.
-
-If you forgot to set an important variable, you may get instead::
-
-  $ GIT_MULTIMAIL_CHECK_SETUP=true /home/moy/dev/git-multimail/git-multimail/git_multimail.py
-  No email recipients configured!
-
-Do not set ``$GIT_MULTIMAIL_CHECK_SETUP`` other than for testing your
-configuration: it would disable the hook completely.
-
-Git is not using the right address in the From/To/Reply-To field
-----------------------------------------------------------------
-
-First, make sure that git-multimail actually uses what you think it is
-using. A lot happens to your email (especially when posting to a
-mailing-list) between the time `git_multimail.py` sends it and the
-time it reaches your inbox.
-
-A simple test (to do on a test repository, do not use in production as
-it would disable email sending): change your post-receive hook to call
-`git_multimail.py` with the `--stdout` option, and try to push to the
-repository. You should see something like::
-
-  Counting objects: 3, done.
-  Writing objects: 100% (3/3), 263 bytes | 0 bytes/s, done.
-  Total 3 (delta 0), reused 0 (delta 0)
-  remote: Sending notification emails to: foo.bar@example.com
-  remote: ===========================================================================
-  remote: Date: Mon, 25 Apr 2016 18:39:59 +0200
-  remote: To: foo.bar@example.com
-  remote: Subject: [git] branch master updated: foo
-  remote: MIME-Version: 1.0
-  remote: Content-Type: text/plain; charset=utf-8
-  remote: Content-Transfer-Encoding: 8bit
-  remote: Message-ID: <20160425163959.2311.20498@anie>
-  remote: From: Auth Or <Foo.Bar@example.com>
-  remote: Reply-To: Auth Or <Foo.Bar@example.com>
-  remote: X-Git-Host: example
-  ...
-  remote: --
-  remote: To stop receiving notification emails like this one, please contact
-  remote: the administrator of this repository.
-  remote: ===========================================================================
-  To /path/to/repo
-     6278f04..e173f20  master -> master
-
-Note: this does not include the sender (Return-Path: header), as it is
-not part of the message content but passed to the mailer. Some mailer
-show the ``Sender:`` field instead of the ``From:`` field (for
-example, Zimbra Webmail shows ``From: <sender-field> on behalf of
-<from-field>``).