From mboxrd@z Thu Jan 1 00:00:00 1970 From: Yann Dirson Subject: [PATCH] Improve documentation for git-sh-setup. Date: Fri, 22 Feb 2008 00:01:28 +0100 Message-ID: <20080221230101.27644.49229.stgit@gandelf.nowhere.earth> Mime-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit To: git@vger.kernel.org X-From: git-owner@vger.kernel.org Fri Feb 22 00:01:30 2008 Return-path: Envelope-to: gcvg-git-2@gmane.org Received: from vger.kernel.org ([209.132.176.167]) by lo.gmane.org with esmtp (Exim 4.50) id 1JSKPn-0004rI-RZ for gcvg-git-2@gmane.org; Fri, 22 Feb 2008 00:01:20 +0100 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753944AbYBUXAo (ORCPT ); Thu, 21 Feb 2008 18:00:44 -0500 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1753571AbYBUXAo (ORCPT ); Thu, 21 Feb 2008 18:00:44 -0500 Received: from smtp3-g19.free.fr ([212.27.42.29]:57428 "EHLO smtp3-g19.free.fr" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753405AbYBUXAn (ORCPT ); Thu, 21 Feb 2008 18:00:43 -0500 Received: from smtp3-g19.free.fr (localhost.localdomain [127.0.0.1]) by smtp3-g19.free.fr (Postfix) with ESMTP id 82B2D17B56B for ; Fri, 22 Feb 2008 00:00:42 +0100 (CET) Received: from gandelf.nowhere.earth (nan92-1-81-57-214-146.fbx.proxad.net [81.57.214.146]) by smtp3-g19.free.fr (Postfix) with ESMTP id 6366317B55F for ; Fri, 22 Feb 2008 00:00:42 +0100 (CET) Received: from gandelf.nowhere.earth (localhost [127.0.0.1]) by gandelf.nowhere.earth (Postfix) with ESMTP id 90AFE1F025 for ; Fri, 22 Feb 2008 00:01:28 +0100 (CET) User-Agent: StGIT/0.14.1 Sender: git-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Archived-At: Signed-off-by: Yann Dirson Cc: Pierre Habouzit --- Documentation/git-sh-setup.txt | 23 ++++++++++++++++++----- 1 files changed, 18 insertions(+), 5 deletions(-) diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt index 16b8b75..75e6846 100644 --- a/Documentation/git-sh-setup.txt +++ b/Documentation/git-sh-setup.txt @@ -19,12 +19,25 @@ Porcelain-ish scripts and/or are writing new ones. The `git-sh-setup` scriptlet is designed to be sourced (using `.`) by other shell scripts to set up some variables pointing at the normal git directories and a few helper shell functions. +It also provides help messages, and some amount of command-line +parsing. -Before sourcing it, your script should set up a few variables; -`USAGE` (and `LONG_USAGE`, if any) is used to define message -given by `usage()` shell function. `SUBDIRECTORY_OK` can be set -if the script can run from a subdirectory of the working tree -(some commands do not). +Before sourcing it, your script should set up a few variables. + +`OPTIONS_SPEC` allows to declare the options so that the command-line +can be pre-processed, and the usage message autogenerated. It must +follow the rules which apply to arguments to `git rev-parse +--parseopt`. If you need `git-rev-parse --parseopt` to keep the `--` +the user may have passed to your command, you should also set +`OPTIONS_KEEPDASHDASH` to a non empty value. + +If the constraints imposed by the use of `git rev-parse` do not fit +for a particular tool, `USAGE` (and `LONG_USAGE`, if any) can be used +to define message given by `usage()` shell function; no command-line +pre-processing occurs, the script has entire control over it. + +`SUBDIRECTORY_OK` can be set if the script can run from a subdirectory +of the working tree (some commands do not). The scriptlet sets `GIT_DIR` and `GIT_OBJECT_DIRECTORY` shell variables, but does *not* export them to the environment.