[Intel-gfx] [DIM PATCH] maintainer-tools: extract the man page from the dim script
Jani Nikula
jani.nikula at intel.com
Mon Oct 19 06:13:06 PDT 2015
Add some magic to find the man page on dim help, and display the man
page like before. Add make target to create dim.html version of the man
page.
---
Makefile | 9 +-
dim | 324 +++------------------------------------------------------------
dim.rst | 309 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 327 insertions(+), 315 deletions(-)
create mode 100644 dim.rst
diff --git a/Makefile b/Makefile
index d95519a00f16..7c18885e24fa 100644
--- a/Makefile
+++ b/Makefile
@@ -4,17 +4,22 @@
# the wavedrom json, copy-pasting to and from http://wavedrom.com/editor.html is
# handy as it shows the result live.
-all: drm-intel.html
+all: drm-intel.html dim.html
%.svg: %.dot
dot -T svg -o $@ $<
+%.html: %.rst
+ rst2html $< > $@
+
# the sed bit here is a hack to make wavedrom process the timeline
drm-intel.html: drm-intel.rst drm-intel-flow.svg drm-intel-timeline.rst drm-intel-timeline.json
rst2html $< > $@
sed -i 's/<body/<body onload="WaveDrom.ProcessAll()"/' $@
+dim.html: dim.rst
+
clean:
- rm -f drm-intel.html drm-intel-flow.svg
+ rm -f drm-intel.html drm-intel-flow.svg dim.html
.PHONY: all clean
diff --git a/dim b/dim
index 4b08291e487d..03e2709159d5 100755
--- a/dim
+++ b/dim
@@ -964,7 +964,16 @@ case "$subcommand" in
rm drivers/gpu/drm/i915/*.ko &> /dev/null || true
make C=1 drivers/gpu/drm/i915/i915.ko
;;
- *)
+ help|*)
+ manpage=$DIM_PREFIX/maintainer-tools/dim.rst
+ if [ ! -e "$manpage" ]; then
+ manpage=$(dirname $(readlink -f $0))/dim.rst
+ if [ ! -e "$manpage" ]; then
+ echo "Can't find the man page. See http://cgit.freedesktop.org/drm-intel/tree/dim.rst?h=maintainer-tools"
+ exit 1
+ fi
+ fi
+
if hash rst2man 2>/dev/null; then
renderer=rst2man
pager="man -l -"
@@ -972,318 +981,7 @@ case "$subcommand" in
renderer=cat
pager=${PAGER:-cat}
fi
- $renderer <<HERE | $pager
-=====
- dim
-=====
-
----------------------------
-drm-intel maintainer script
----------------------------
-
-:Author: Daniel Vetter <daniel.vetter at ffwll.ch>
-:Author: Jani Nikula <jani.nikula at intel.com>
-:Date: 2014-05-15
-:Copyright: 2012-2015 Intel Corporation
-:Manual section: 1
-:Manual group: maintainer tools
-
-SYNOPSIS
-========
-
-**dim** [*option* ...] *command*
-
-DESCRIPTION
-===========
-
-drm-intel maintainer script.
-
-Branch Model
-------------
-
-The dim flow has 3 main development branches:
-
-- drm-intel-next-queued for feature work. This branch gets regularly pushed to
- drm-intel-next and tagged and then sent on to the upstream drm-next branch
- using *update-next*. The cut-off for the last pull request to drm-next is
- around -rc5. After that point patches in drm-intel-next-queued already aim at
- the next but one and not the next merge window.
-
-- drm-intel-next-fixes is to collect fixes for the current merge window after
- the -rc5 feature cut-off in drm-next.
-
-- drm-intel-fixes is for fixes for the current -rc1 kernel. This is separate
- from drm-intel-next-fixes since the merge window feature cutoff at -rc5 is a
- few weeks ahead of the final release of the previous kernel.
-
- There's separate tracking branches for inclusion into linux-next to make sure
- that the feature work in drm-intel-next-queued aimed for the next but one
- merge window doesn't cause unecassary conflicts in linux-next - in that case
- only drm-intel-next-fixes is included in linux-next. The switchover happens
- when drm-intel-fixes has caught up (in git terms: drm-intel-next-fixes is
- direct ancestor of drm-intel-fixes). Therefore only roll drm-intel-fixes
- forward once -rc1 is released
-
-In addition there's 2 permanent topic branches:
-
-- topic/drm-misc carries core drm patches aimed at the next merge window.
-
-- topic/drm-fixes carries core drm fixes for the current -rc kernels.
-
-Additional topic branches are created as needed using *create-branch* and
-*remove-branch*.
-
-OPTIONS
-=======
-
--f Ignore some error conditions.
--d Dry run.
--i Interactive mode.
-
-COMMANDS
-========
-
-setup *prefix*
---------------
-Setup git maintainer branches in the given prefix.
-
-nightly-forget
---------------
-Forget git rerere solutions for nightly merges in case they
-contain a bogus merge resolution.
-
-update-branches
----------------
-Updates all maintainer branches. Only needs to be run to synchronize branches
-between different machines (or maintainers fwiw). As long a given branch is
-always maintained from the same machine, even if different branches are
-maintained on different machines (by different maintainers), there's no need to
-run this command.
-
-rebuild-nightly
----------------
-Rebuilds the nightly branch. Useful when ad-hoc trees are
-included in -nightly.
-
-cat-to-fixup
-------------
-
-Pipes stdin into the fixup patch file for the current -nightly merge.
-
-push-branch branch [*git push arguments*]
------------------------------------------
-
-push-fixes|pf [*git push arguments*]
-------------------------------------
-
-push-next-fixes|pnf [*git push arguments*]
-------------------------------------------
-
-push-queued|pq [*git push arguments*]
--------------------------------------
-
-Updates the named branch, or drm-intel-fixes, drm-intel-next-fixes or the
-drm-intel-next-queued branch respectively. Complains if that's not the current
-branch, assuming that patches got merged to the wrong branch. After pushing also
-updates linux-next and drm-intel-nightly branches.
-
-checkout *branch*
------------------
-Checks out the named branch.
-
-co
---
-
-cof
----
-
-conf
-----
-Checks out the drm-intel-fixes branch, dinf or dinq respectively for merging
-patches.
-
-apply-branch|ab|sob branch [*git am arguments*]
------------------------------------------------
-Applys a patch to the given branch, complaining if it is not
-checked out yet.
-
-apply-fixes|af [*git am arguments*]
------------------------------------
-
-apply-next-fixes|anf [*git am arguments*]
------------------------------------------
-
-apply-queued|aq [*git am arguments*]
-------------------------------------
-Applies a patch to -fixes, -next-fixes or -next-queued respectively, complains
-if it's not the right branch. Additional arguments are passed to git am.
-
-magic-patch|mp [-a]
--------------------
-Apply a patch using patch and then wiggle in any conflicts. When passing the
-option -a automatically changes the working directory into the git repository
-used by the last previous branch-specific command. This is useful with the
-per-branch workdir model.
-
-magic-rebase-resolve|mrr
-------------------------
-Tries to resolve a rebase conflict by first resetting the tree
-and the using the magic patch tool. Then builds the tree, adds
-any changes with git add -u and continues the rebase.
-
-cd
---
-Changes the working directory into the git repository used by the last previous
-branch-specific command. This is implemented as a bash-function to make it
-useful in interactive shells and scripts. Only available when the bash
-completion is sourced.
-
-apply-resolved|ar
------------------
-Compile-test the current tree and if successfully resolve a
-confilicted git am. Also runs the patch checker afterwards.
-
-apply-igt|ai
-------------
-Apply a patch to the i-g-t repository.
-
-tc *commit-ish*
----------------
-Prints the linux kernel tag which contains the supplied commit-ish
-
-check-patch|cp [*commit-ish* [.. *commit-ish*]]
------------------------------------------------
-Runs the given commit range commit-ish..commit-ish through the check tools. If
-no commit-ish is passed, defaults to HEAD^..HEAD. If one commit-ish is passed
-instead of a range, the range commit-ish..HEAD is used.
-
-cherry-pick *commit-ish* [*git cherry-pick arguments*]
-------------------------------------------------------
-
-Improved git cherry-pick version which also scans drm-intel-nightly for any
-mentions of the cherry-picked commit. Should be used when cherry-pick from -next
-to -fixes to make sure all fixups are picked, too. In dry-run mode/-d only the
-patch list is generated.
-
-pull-request *branch* *upstream*
---------------------------------
-Fetch the *upstream* remote to make sure it's up-to-date, create and push a date
-based tag for the *branch*, generate a pull request template with the specified
-*upstream*, and finally start \$DIM_MUA with the template with subject and
-recipients already set.
-
-Since the tag for the *branch* is date based, the pull request can be
-regenerated with the same commands if something goes wrong.
-
-pull-request-fixes [*upstream*]
--------------------------------
-This is a special case of **pull-request**, with *drm-intel-fixes* as the
-branch and *origin/master* as the default upstream.
-
-pull-request-next-fixes [*upstream*]
-------------------------------------
-This is a special case of **pull-request**, with *drm-intel-next-fixes* as
-the branch and *\$DRM_UPSTREAM/drm-next* as the default upstream.
-
-pull-request-next [*upstream*]
-------------------------------
-This is similar to **pull-request**, but for feature pull requests, with
-*drm-intel-next* as the branch and *\$DRM_UPSTREAM/drm-next* as the default
-upstream.
-
-The difference to **pull-request** is that this command does not generate a
-tag; this must have been done previously using **update-next**. This also means
-that the pull request can be regenerated with the same commands if something
-goes wrong.
-
-update-next
------------
-Pushes out the latest dinq to drm-intel-next and tags it. Also
-pushes out the latest nightly to drm-intel-testing. For an
-overview a gitk view of the currently unmerged feature pile is
-opened.
-
-Also checks that the drm-intel-fixes|-next-queued are fully
-merged into -nightly to avoid operator error.
-
-tag-next
---------
-
-Pushes a new tag for the current drm-intel-next state after checking that the
-remote is up-to-date. Useful if drm-intel-next has been changed since the last
-run of the update-next command (e.g. to apply a hotfix before sending out the
-pull request).
-
-checker
--------
-Run sparse on the kernel.
-
-create-branch *branch* [*commit-ish*]
--------------------------------------
-
-Create a new topic branch with the given name. Note that topic/ is not
-automatically prepended. The branch starts at HEAD or the given commit-ish.
-
-remove-branch *branch*
-----------------------
-
-Remove the given topic branch.
-
-create-workdir (*branch* | all)
--------------------------------
-
-Create a separate workdir for the branch with the given name (requires that
-git-new-workdir from git-core contrib is installed), or for all branches if
-"all" is given.
-
-for-each-workdir|fw *command*
------------------------------
-
-Run the given command in all active workdirs including the main repository under
-\$DIM_DRM_INTEL.
-
-help
-----
-Show this help. Install **rst2man(1)** for best results.
-
-ENVIRONMENT
-===========
-
-DIM_CONFIG
-----------
-Path to the dim configuration file, \$HOME/.dimrc by default, which is sourced
-if it exists. It can be used to set other environment variables to control dim.
-
-DIM_PREFIX
-----------
-Path prefix for kernel repositories.
-
-DIM_DRM_INTEL
--------------
-The main maintainer repository under \$DIM_PREFIX.
-
-DIM_DRM_INTEL_REMOTE
---------------------
-Name of the $drm_intel_ssh remote within \$DIM_DRM_INTEL.
-
-DIM_DRM_UPSTREAM_REMOTE
------------------------
-Name of the $drm_upstream_git remote within \$DIM_DRM_INTEL.
-
-DIM_MUA
--------
-Mail user agent. Must support the following subset of **mutt(1)** command line
-options: \$DIM_MUA [-s subject] [-i file] [-c cc-addr] to-addr [...]
-
-DIM_TEMPLATE_HELLO
-------------------
-Path to a file containing a greeting template for pull request mails.
-
-DIM_TEMPLATE_SIGNATURE
-----------------------
-Path to a file containing a signature template for pull request mails.
-HERE
- exit 0
+ $renderer < $manpage | $pager
;;
esac
diff --git a/dim.rst b/dim.rst
new file mode 100644
index 000000000000..da5fdd3a814d
--- /dev/null
+++ b/dim.rst
@@ -0,0 +1,309 @@
+=====
+ dim
+=====
+
+---------------------------
+drm-intel maintainer script
+---------------------------
+
+:Author: Daniel Vetter <daniel.vetter at ffwll.ch>
+:Author: Jani Nikula <jani.nikula at intel.com>
+:Date: 2014-05-15
+:Copyright: 2012-2015 Intel Corporation
+:Manual section: 1
+:Manual group: maintainer tools
+
+SYNOPSIS
+========
+
+**dim** [*option* ...] *command*
+
+DESCRIPTION
+===========
+
+drm-intel maintainer script.
+
+Branch Model
+------------
+
+The dim flow has 3 main development branches:
+
+- drm-intel-next-queued for feature work. This branch gets regularly pushed to
+ drm-intel-next and tagged and then sent on to the upstream drm-next branch
+ using *update-next*. The cut-off for the last pull request to drm-next is
+ around -rc5. After that point patches in drm-intel-next-queued already aim at
+ the next but one and not the next merge window.
+
+- drm-intel-next-fixes is to collect fixes for the current merge window after
+ the -rc5 feature cut-off in drm-next.
+
+- drm-intel-fixes is for fixes for the current -rc1 kernel. This is separate
+ from drm-intel-next-fixes since the merge window feature cutoff at -rc5 is a
+ few weeks ahead of the final release of the previous kernel.
+
+ There's separate tracking branches for inclusion into linux-next to make sure
+ that the feature work in drm-intel-next-queued aimed for the next but one
+ merge window doesn't cause unecassary conflicts in linux-next - in that case
+ only drm-intel-next-fixes is included in linux-next. The switchover happens
+ when drm-intel-fixes has caught up (in git terms: drm-intel-next-fixes is
+ direct ancestor of drm-intel-fixes). Therefore only roll drm-intel-fixes
+ forward once -rc1 is released
+
+In addition there's 2 permanent topic branches:
+
+- topic/drm-misc carries core drm patches aimed at the next merge window.
+
+- topic/drm-fixes carries core drm fixes for the current -rc kernels.
+
+Additional topic branches are created as needed using *create-branch* and
+*remove-branch*.
+
+OPTIONS
+=======
+
+-f Ignore some error conditions.
+-d Dry run.
+-i Interactive mode.
+
+COMMANDS
+========
+
+setup *prefix*
+--------------
+Setup git maintainer branches in the given prefix.
+
+nightly-forget
+--------------
+Forget git rerere solutions for nightly merges in case they
+contain a bogus merge resolution.
+
+update-branches
+---------------
+Updates all maintainer branches. Only needs to be run to synchronize branches
+between different machines (or maintainers fwiw). As long a given branch is
+always maintained from the same machine, even if different branches are
+maintained on different machines (by different maintainers), there's no need to
+run this command.
+
+rebuild-nightly
+---------------
+Rebuilds the nightly branch. Useful when ad-hoc trees are
+included in -nightly.
+
+cat-to-fixup
+------------
+
+Pipes stdin into the fixup patch file for the current -nightly merge.
+
+push-branch branch [*git push arguments*]
+-----------------------------------------
+
+push-fixes|pf [*git push arguments*]
+------------------------------------
+
+push-next-fixes|pnf [*git push arguments*]
+------------------------------------------
+
+push-queued|pq [*git push arguments*]
+-------------------------------------
+
+Updates the named branch, or drm-intel-fixes, drm-intel-next-fixes or the
+drm-intel-next-queued branch respectively. Complains if that's not the current
+branch, assuming that patches got merged to the wrong branch. After pushing also
+updates linux-next and drm-intel-nightly branches.
+
+checkout *branch*
+-----------------
+Checks out the named branch.
+
+co
+--
+
+cof
+---
+
+conf
+----
+Checks out the drm-intel-fixes branch, dinf or dinq respectively for merging
+patches.
+
+apply-branch|ab|sob branch [*git am arguments*]
+-----------------------------------------------
+Applys a patch to the given branch, complaining if it is not
+checked out yet.
+
+apply-fixes|af [*git am arguments*]
+-----------------------------------
+
+apply-next-fixes|anf [*git am arguments*]
+-----------------------------------------
+
+apply-queued|aq [*git am arguments*]
+------------------------------------
+Applies a patch to -fixes, -next-fixes or -next-queued respectively, complains
+if it's not the right branch. Additional arguments are passed to git am.
+
+magic-patch|mp [-a]
+-------------------
+Apply a patch using patch and then wiggle in any conflicts. When passing the
+option -a automatically changes the working directory into the git repository
+used by the last previous branch-specific command. This is useful with the
+per-branch workdir model.
+
+magic-rebase-resolve|mrr
+------------------------
+Tries to resolve a rebase conflict by first resetting the tree
+and the using the magic patch tool. Then builds the tree, adds
+any changes with git add -u and continues the rebase.
+
+cd
+--
+Changes the working directory into the git repository used by the last previous
+branch-specific command. This is implemented as a bash-function to make it
+useful in interactive shells and scripts. Only available when the bash
+completion is sourced.
+
+apply-resolved|ar
+-----------------
+Compile-test the current tree and if successfully resolve a
+confilicted git am. Also runs the patch checker afterwards.
+
+apply-igt|ai
+------------
+Apply a patch to the i-g-t repository.
+
+tc *commit-ish*
+---------------
+Prints the linux kernel tag which contains the supplied commit-ish
+
+check-patch|cp [*commit-ish* [.. *commit-ish*]]
+-----------------------------------------------
+Runs the given commit range commit-ish..commit-ish through the check tools. If
+no commit-ish is passed, defaults to HEAD^..HEAD. If one commit-ish is passed
+instead of a range, the range commit-ish..HEAD is used.
+
+cherry-pick *commit-ish* [*git cherry-pick arguments*]
+------------------------------------------------------
+
+Improved git cherry-pick version which also scans drm-intel-nightly for any
+mentions of the cherry-picked commit. Should be used when cherry-pick from -next
+to -fixes to make sure all fixups are picked, too. In dry-run mode/-d only the
+patch list is generated.
+
+pull-request *branch* *upstream*
+--------------------------------
+Fetch the *upstream* remote to make sure it's up-to-date, create and push a date
+based tag for the *branch*, generate a pull request template with the specified
+*upstream*, and finally start \$DIM_MUA with the template with subject and
+recipients already set.
+
+Since the tag for the *branch* is date based, the pull request can be
+regenerated with the same commands if something goes wrong.
+
+pull-request-fixes [*upstream*]
+-------------------------------
+This is a special case of **pull-request**, with *drm-intel-fixes* as the
+branch and *origin/master* as the default upstream.
+
+pull-request-next-fixes [*upstream*]
+------------------------------------
+This is a special case of **pull-request**, with *drm-intel-next-fixes* as
+the branch and *\$DRM_UPSTREAM/drm-next* as the default upstream.
+
+pull-request-next [*upstream*]
+------------------------------
+This is similar to **pull-request**, but for feature pull requests, with
+*drm-intel-next* as the branch and *\$DRM_UPSTREAM/drm-next* as the default
+upstream.
+
+The difference to **pull-request** is that this command does not generate a
+tag; this must have been done previously using **update-next**. This also means
+that the pull request can be regenerated with the same commands if something
+goes wrong.
+
+update-next
+-----------
+Pushes out the latest dinq to drm-intel-next and tags it. Also
+pushes out the latest nightly to drm-intel-testing. For an
+overview a gitk view of the currently unmerged feature pile is
+opened.
+
+Also checks that the drm-intel-fixes|-next-queued are fully
+merged into -nightly to avoid operator error.
+
+tag-next
+--------
+
+Pushes a new tag for the current drm-intel-next state after checking that the
+remote is up-to-date. Useful if drm-intel-next has been changed since the last
+run of the update-next command (e.g. to apply a hotfix before sending out the
+pull request).
+
+checker
+-------
+Run sparse on the kernel.
+
+create-branch *branch* [*commit-ish*]
+-------------------------------------
+
+Create a new topic branch with the given name. Note that topic/ is not
+automatically prepended. The branch starts at HEAD or the given commit-ish.
+
+remove-branch *branch*
+----------------------
+
+Remove the given topic branch.
+
+create-workdir (*branch* | all)
+-------------------------------
+
+Create a separate workdir for the branch with the given name (requires that
+git-new-workdir from git-core contrib is installed), or for all branches if
+"all" is given.
+
+for-each-workdir|fw *command*
+-----------------------------
+
+Run the given command in all active workdirs including the main repository under
+\$DIM_DRM_INTEL.
+
+help
+----
+Show this help. Install **rst2man(1)** for best results.
+
+ENVIRONMENT
+===========
+
+DIM_CONFIG
+----------
+Path to the dim configuration file, \$HOME/.dimrc by default, which is sourced
+if it exists. It can be used to set other environment variables to control dim.
+
+DIM_PREFIX
+----------
+Path prefix for kernel repositories.
+
+DIM_DRM_INTEL
+-------------
+The main maintainer repository under \$DIM_PREFIX.
+
+DIM_DRM_INTEL_REMOTE
+--------------------
+Name of the $drm_intel_ssh remote within \$DIM_DRM_INTEL.
+
+DIM_DRM_UPSTREAM_REMOTE
+-----------------------
+Name of the $drm_upstream_git remote within \$DIM_DRM_INTEL.
+
+DIM_MUA
+-------
+Mail user agent. Must support the following subset of **mutt(1)** command line
+options: \$DIM_MUA [-s subject] [-i file] [-c cc-addr] to-addr [...]
+
+DIM_TEMPLATE_HELLO
+------------------
+Path to a file containing a greeting template for pull request mails.
+
+DIM_TEMPLATE_SIGNATURE
+----------------------
+Path to a file containing a signature template for pull request mails.
--
2.1.4
More information about the Intel-gfx
mailing list