man1/git-mergetool.1

   1 '\" t
   2 .\"     Title: git-mergetool
   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: 12/10/2021
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.34.1.182.ge773545c7f
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-MERGETOOL" "1" "12/10/2021" "Git 2\&.34\&.1\&.182\&.ge77354" "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-mergetool \- Run merge conflict resolution tools to resolve merge conflicts
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fIgit mergetool\fR [\-\-tool=<tool>] [\-y | \-\-[no\-]prompt] [<file>\&...]
  36 .fi
  37 .sp
  38 .SH "DESCRIPTION"
  39 .sp
  40 Use \fBgit mergetool\fR to run one of several merge utilities to resolve merge conflicts\&. It is typically run after \fIgit merge\fR\&.
  41 .sp
  42 If one or more <file> parameters are given, the merge tool program will be run to resolve differences on each file (skipping those without conflicts)\&. Specifying a directory will include all unresolved files in that path\&. If no <file> names are specified, \fIgit mergetool\fR will run the merge tool program on every file with merge conflicts\&.
  43 .SH "OPTIONS"
  44 .PP
  45 \-t <tool>, \-\-tool=<tool>
  46 .RS 4
  47 Use the merge resolution program specified by <tool>\&. Valid values include emerge, gvimdiff, kdiff3, meld, vimdiff, and tortoisemerge\&. Run
  48 \fBgit mergetool \-\-tool\-help\fR
  49 for the list of valid <tool> settings\&.
  50 .sp
  51 If a merge resolution program is not specified,
  52 \fIgit mergetool\fR
  53 will use the configuration variable
  54 \fBmerge\&.tool\fR\&. If the configuration variable
  55 \fBmerge\&.tool\fR
  56 is not set,
  57 \fIgit mergetool\fR
  58 will pick a suitable default\&.
  59 .sp
  60 You can explicitly provide a full path to the tool by setting the configuration variable
  61 \fBmergetool\&.<tool>\&.path\fR\&. For example, you can configure the absolute path to kdiff3 by setting
  62 \fBmergetool\&.kdiff3\&.path\fR\&. Otherwise,
  63 \fIgit mergetool\fR
  64 assumes the tool is available in PATH\&.
  65 .sp
  66 Instead of running one of the known merge tool programs,
  67 \fIgit mergetool\fR
  68 can be customized to run an alternative program by specifying the command line to invoke in a configuration variable
  69 \fBmergetool\&.<tool>\&.cmd\fR\&.
  70 .sp
  71 When
  72 \fIgit mergetool\fR
  73 is invoked with this tool (either through the
  74 \fB\-t\fR
  75 or
  76 \fB\-\-tool\fR
  77 option or the
  78 \fBmerge\&.tool\fR
  79 configuration variable) the configured command line will be invoked with
  80 \fB$BASE\fR
  81 set to the name of a temporary file containing the common base for the merge, if available;
  82 \fB$LOCAL\fR
  83 set to the name of a temporary file containing the contents of the file on the current branch;
  84 \fB$REMOTE\fR
  85 set to the name of a temporary file containing the contents of the file to be merged, and
  86 \fB$MERGED\fR
  87 set to the name of the file to which the merge tool should write the result of the merge resolution\&.
  88 .sp
  89 If the custom merge tool correctly indicates the success of a merge resolution with its exit code, then the configuration variable
  90 \fBmergetool\&.<tool>\&.trustExitCode\fR
  91 can be set to
  92 \fBtrue\fR\&. Otherwise,
  93 \fIgit mergetool\fR
  94 will prompt the user to indicate the success of the resolution after the custom tool has exited\&.
  95 .RE
  96 .PP
  97 \-\-tool\-help
  98 .RS 4
  99 Print a list of merge tools that may be used with
 100 \fB\-\-tool\fR\&.
 101 .RE
 102 .PP
 103 \-y, \-\-no\-prompt
 104 .RS 4
 105 Don\(cqt prompt before each invocation of the merge resolution program\&. This is the default if the merge resolution program is explicitly specified with the
 106 \fB\-\-tool\fR
 107 option or with the
 108 \fBmerge\&.tool\fR
 109 configuration variable\&.
 110 .RE
 111 .PP
 112 \-\-prompt
 113 .RS 4
 114 Prompt before each invocation of the merge resolution program to give the user a chance to skip the path\&.
 115 .RE
 116 .PP
 117 \-g, \-\-gui
 118 .RS 4
 119 When
 120 \fIgit\-mergetool\fR
 121 is invoked with the
 122 \fB\-g\fR
 123 or
 124 \fB\-\-gui\fR
 125 option the default merge tool will be read from the configured
 126 \fBmerge\&.guitool\fR
 127 variable instead of
 128 \fBmerge\&.tool\fR\&. If
 129 \fBmerge\&.guitool\fR
 130 is not set, we will fallback to the tool configured under
 131 \fBmerge\&.tool\fR\&.
 132 .RE
 133 .PP
 134 \-\-no\-gui
 135 .RS 4
 136 This overrides a previous
 137 \fB\-g\fR
 138 or
 139 \fB\-\-gui\fR
 140 setting and reads the default merge tool will be read from the configured
 141 \fBmerge\&.tool\fR
 142 variable\&.
 143 .RE
 144 .PP
 145 \-O<orderfile>
 146 .RS 4
 147 Process files in the order specified in the <orderfile>, which has one shell glob pattern per line\&. This overrides the
 148 \fBdiff\&.orderFile\fR
 149 configuration variable (see
 150 \fBgit-config\fR(1))\&. To cancel
 151 \fBdiff\&.orderFile\fR, use
 152 \fB\-O/dev/null\fR\&.
 153 .RE
 154 .SH "CONFIGURATION"
 155 .PP
 156 mergetool\&.<tool>\&.path
 157 .RS 4
 158 Override the path for the given tool\&. This is useful in case your tool is not in the PATH\&.
 159 .RE
 160 .PP
 161 mergetool\&.<tool>\&.cmd
 162 .RS 4
 163 Specify the command to invoke the specified merge tool\&. The specified command is evaluated in shell with the following variables available:
 164 \fIBASE\fR
 165 is the name of a temporary file containing the common base of the files to be merged, if available;
 166 \fILOCAL\fR
 167 is the name of a temporary file containing the contents of the file on the current branch;
 168 \fIREMOTE\fR
 169 is the name of a temporary file containing the contents of the file from the branch being merged;
 170 \fIMERGED\fR
 171 contains the name of the file to which the merge tool should write the results of a successful merge\&.
 172 .RE
 173 .PP
 174 mergetool\&.<tool>\&.hideResolved
 175 .RS 4
 176 Allows the user to override the global
 177 \fBmergetool\&.hideResolved\fR
 178 value for a specific tool\&. See
 179 \fBmergetool\&.hideResolved\fR
 180 for the full description\&.
 181 .RE
 182 .PP
 183 mergetool\&.<tool>\&.trustExitCode
 184 .RS 4
 185 For a custom merge command, specify whether the exit code of the merge command can be used to determine whether the merge was successful\&. If this is not set to true then the merge target file timestamp is checked and the merge assumed to have been successful if the file has been updated, otherwise the user is prompted to indicate the success of the merge\&.
 186 .RE
 187 .PP
 188 mergetool\&.meld\&.hasOutput
 189 .RS 4
 190 Older versions of
 191 \fBmeld\fR
 192 do not support the
 193 \fB\-\-output\fR
 194 option\&. Git will attempt to detect whether
 195 \fBmeld\fR
 196 supports
 197 \fB\-\-output\fR
 198 by inspecting the output of
 199 \fBmeld \-\-help\fR\&. Configuring
 200 \fBmergetool\&.meld\&.hasOutput\fR
 201 will make Git skip these checks and use the configured value instead\&. Setting
 202 \fBmergetool\&.meld\&.hasOutput\fR
 203 to
 204 \fBtrue\fR
 205 tells Git to unconditionally use the
 206 \fB\-\-output\fR
 207 option, and
 208 \fBfalse\fR
 209 avoids using
 210 \fB\-\-output\fR\&.
 211 .RE
 212 .PP
 213 mergetool\&.meld\&.useAutoMerge
 214 .RS 4
 215 When the
 216 \fB\-\-auto\-merge\fR
 217 is given, meld will merge all non\-conflicting parts automatically, highlight the conflicting parts and wait for user decision\&. Setting
 218 \fBmergetool\&.meld\&.useAutoMerge\fR
 219 to
 220 \fBtrue\fR
 221 tells Git to unconditionally use the
 222 \fB\-\-auto\-merge\fR
 223 option with
 224 \fBmeld\fR\&. Setting this value to
 225 \fBauto\fR
 226 makes git detect whether
 227 \fB\-\-auto\-merge\fR
 228 is supported and will only use
 229 \fB\-\-auto\-merge\fR
 230 when available\&. A value of
 231 \fBfalse\fR
 232 avoids using
 233 \fB\-\-auto\-merge\fR
 234 altogether, and is the default value\&.
 235 .RE
 236 .PP
 237 mergetool\&.hideResolved
 238 .RS 4
 239 During a merge Git will automatically resolve as many conflicts as possible and write the
 240 \fIMERGED\fR
 241 file containing conflict markers around any conflicts that it cannot resolve;
 242 \fILOCAL\fR
 243 and
 244 \fIREMOTE\fR
 245 normally represent the versions of the file from before Git\(cqs conflict resolution\&. This flag causes
 246 \fILOCAL\fR
 247 and
 248 \fIREMOTE\fR
 249 to be overwriten so that only the unresolved conflicts are presented to the merge tool\&. Can be configured per\-tool via the
 250 \fBmergetool\&.<tool>\&.hideResolved\fR
 251 configuration variable\&. Defaults to
 252 \fBfalse\fR\&.
 253 .RE
 254 .PP
 255 mergetool\&.keepBackup
 256 .RS 4
 257 After performing a merge, the original file with conflict markers can be saved as a file with a
 258 \fB\&.orig\fR
 259 extension\&. If this variable is set to
 260 \fBfalse\fR
 261 then this file is not preserved\&. Defaults to
 262 \fBtrue\fR
 263 (i\&.e\&. keep the backup files)\&.
 264 .RE
 265 .PP
 266 mergetool\&.keepTemporaries
 267 .RS 4
 268 When invoking a custom merge tool, Git uses a set of temporary files to pass to the tool\&. If the tool returns an error and this variable is set to
 269 \fBtrue\fR, then these temporary files will be preserved, otherwise they will be removed after the tool has exited\&. Defaults to
 270 \fBfalse\fR\&.
 271 .RE
 272 .PP
 273 mergetool\&.writeToTemp
 274 .RS 4
 275 Git writes temporary
 276 \fIBASE\fR,
 277 \fILOCAL\fR, and
 278 \fIREMOTE\fR
 279 versions of conflicting files in the worktree by default\&. Git will attempt to use a temporary directory for these files when set
 280 \fBtrue\fR\&. Defaults to
 281 \fBfalse\fR\&.
 282 .RE
 283 .PP
 284 mergetool\&.prompt
 285 .RS 4
 286 Prompt before each invocation of the merge resolution program\&.
 287 .RE
 288 .SH "TEMPORARY FILES"
 289 .sp
 290 \fBgit mergetool\fR creates \fB*\&.orig\fR backup files while resolving merges\&. These are safe to remove once a file has been merged and its \fBgit mergetool\fR session has completed\&.
 291 .sp
 292 Setting the \fBmergetool\&.keepBackup\fR configuration variable to \fBfalse\fR causes \fBgit mergetool\fR to automatically remove the backup as files are successfully merged\&.
 293 .SH "GIT"
 294 .sp
 295 Part of the \fBgit\fR(1) suite