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 vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2023-09-13
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.42.0.176.gd6c51973e4
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-SH\-SETUP" "1" "2023\-09\-13" "Git 2\&.42\&.0\&.176\&.gd6c519" "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 .sp
  38 .SH "DESCRIPTION"
  39 .sp
  40 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\&.
  41 .sp
  42 The \fIgit sh\-setup\fR scriptlet is designed to be sourced (using \fB\&.\fR) by other shell scripts to set up some variables pointing at the normal Git directories and a few helper shell functions\&.
  43 .sp
  44 Before sourcing it, your script should set up a few variables; \fBUSAGE\fR (and \fBLONG_USAGE\fR, if any) is used to define 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)\&.
  45 .sp
  46 The scriptlet sets \fBGIT_DIR\fR and \fBGIT_OBJECT_DIRECTORY\fR shell variables, but does \fBnot\fR export them to the environment\&.
  47 .SH "FUNCTIONS"
  48 .PP
  49 die
  50 .RS 4
  51 exit after emitting the supplied error message to the standard error stream\&.
  52 .RE
  53 .PP
  54 usage
  55 .RS 4
  56 die with the usage message\&.
  57 .RE
  58 .PP
  59 set_reflog_action
  60 .RS 4
  61 Set
  62 \fBGIT_REFLOG_ACTION\fR
  63 environment to a given string (typically the name of the program) unless it is already set\&. Whenever the script runs a
  64 \fBgit\fR
  65 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\&.
  66 .RE
  67 .PP
  68 git_editor
  69 .RS 4
  70 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\&.
  71 .RE
  72 .PP
  73 is_bare_repository
  74 .RS 4
  75 outputs
  76 \fBtrue\fR
  77 or
  78 \fBfalse\fR
  79 to the standard output stream to indicate if the repository is a bare repository (i\&.e\&. without an associated working tree)\&.
  80 .RE
  81 .PP
  82 cd_to_toplevel
  83 .RS 4
  84 runs chdir to the toplevel of the working tree\&.
  85 .RE
  86 .PP
  87 require_work_tree
  88 .RS 4
  89 checks if the current directory is within the working tree of the repository, and otherwise dies\&.
  90 .RE
  91 .PP
  92 require_work_tree_exists
  93 .RS 4
  94 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\&.
  95 .RE
  96 .PP
  97 require_clean_work_tree <action> [<hint>]
  98 .RS 4
  99 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
 100 \fBCannot <action>: <reason>\&. <hint>\fR, and dies\&. Example:
 101 .sp
 102 .if n \{\
 103 .RS 4
 104 .\}
 105 .nf
 106 require_clean_work_tree rebase "Please commit or stash them\&."
 107 .fi
 108 .if n \{\
 109 .RE
 110 .\}
 111 .sp
 112 .RE
 113 .PP
 114 get_author_ident_from_commit
 115 .RS 4
 116 outputs code for use with eval to set the GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL and GIT_AUTHOR_DATE variables for a given commit\&.
 117 .RE
 118 .PP
 119 create_virtual_base
 120 .RS 4
 121 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\&.
 122 .RE
 123 .SH "GIT"
 124 .sp
 125 Part of the \fBgit\fR(1) suite