man1/git-sh-setup.1

   1 '\" t
   2 .\"     Title: git-sh-setup
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
   5 .\"      Date: 2024-11-20
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.47.0.305.g4083a6f052
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-SH\-SETUP" "1" "2024-11-20" "Git 2\&.47\&.0\&.305\&.g4083a6" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 git-sh-setup \- Common Git shell script setup code
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fI\&. "$(git \-\-exec\-path)/git\-sh\-setup"\fR
  36 .fi
  37 .SH "DESCRIPTION"
  38 .sp
  39 This is not a command the end user would want to run\&. Ever\&. This documentation is meant for people who are studying the Porcelain\-ish scripts and/or are writing new ones\&.
  40 .sp
  41 The \fIgit sh\-setup\fR 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\&.
  42 .sp
  43 Before sourcing it, your script should set up a few variables; \fBUSAGE\fR (and \fBLONG_USAGE\fR, if any) is used to define the message given by \fBusage\fR() shell function\&. \fBSUBDIRECTORY_OK\fR can be set if the script can run from a subdirectory of the working tree (some commands do not)\&.
  44 .sp
  45 The scriptlet sets \fBGIT_DIR\fR and \fBGIT_OBJECT_DIRECTORY\fR shell variables, but does \fBnot\fR export them to the environment\&.
  46 .SH "FUNCTIONS"
  47 .PP
  48 die
  49 .RS 4
  50 exit after emitting the supplied error message to the standard error stream\&.
  51 .RE
  52 .PP
  53 usage
  54 .RS 4
  55 die with the usage message\&.
  56 .RE
  57 .PP
  58 set_reflog_action
  59 .RS 4
  60 Set
  61 \fBGIT_REFLOG_ACTION\fR
  62 environment to a given string (typically the name of the program) unless it is already set\&. Whenever the script runs a
  63 \fBgit\fR
  64 command that updates refs, a reflog entry is created using the value of this string to leave the record of what command updated the ref\&.
  65 .RE
  66 .PP
  67 git_editor
  68 .RS 4
  69 runs an editor of user\(cqs choice (GIT_EDITOR, core\&.editor, VISUAL or EDITOR) on a given file, but error out if no editor is specified and the terminal is dumb\&.
  70 .RE
  71 .PP
  72 is_bare_repository
  73 .RS 4
  74 outputs
  75 \fBtrue\fR
  76 or
  77 \fBfalse\fR
  78 to the standard output stream to indicate if the repository is a bare repository (i\&.e\&. without an associated working tree)\&.
  79 .RE
  80 .PP
  81 cd_to_toplevel
  82 .RS 4
  83 runs chdir to the toplevel of the working tree\&.
  84 .RE
  85 .PP
  86 require_work_tree
  87 .RS 4
  88 checks if the current directory is within the working tree of the repository, and otherwise dies\&.
  89 .RE
  90 .PP
  91 require_work_tree_exists
  92 .RS 4
  93 checks if the working tree associated with the repository exists, and otherwise dies\&. Often done before calling cd_to_toplevel, which is impossible to do if there is no working tree\&.
  94 .RE
  95 .PP
  96 require_clean_work_tree <action> [<hint>]
  97 .RS 4
  98 checks that the working tree and index associated with the repository have no uncommitted changes to tracked files\&. Otherwise it emits an error message of the form
  99 \fBCannot\fR
 100 \fI<action>\fR\fB:\fR
 101 \fI<reason>\fR\&.
 102 \fI<hint>\fR, and dies\&. Example:
 103 .sp
 104 .if n \{\
 105 .RS 4
 106 .\}
 107 .nf
 108 require_clean_work_tree rebase "Please commit or stash them\&."
 109 .fi
 110 .if n \{\
 111 .RE
 112 .\}
 113 .RE
 114 .PP
 115 get_author_ident_from_commit
 116 .RS 4
 117 outputs code for use with eval to set the GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL and GIT_AUTHOR_DATE variables for a given commit\&.
 118 .RE
 119 .PP
 120 create_virtual_base
 121 .RS 4
 122 modifies the first file so only lines in common with the second file remain\&. If there is insufficient common material, then the first file is left empty\&. The result is suitable as a virtual base input for a 3\-way merge\&.
 123 .RE
 124 .SH "GIT"
 125 .sp
 126 Part of the \fBgit\fR(1) suite