branch: new autosetupmerge option 'simple' for matching branches

With the default push.default option, "simple", beginners are
protected from accidentally pushing to the "wrong" branch in
centralized workflows: if the remote tracking branch they would push
to does not have the same name as the local branch, and they try to do
a "default push", they get an error and explanation with options.

There is a particular centralized workflow where this often happens:
a user branches to a new local topic branch from an existing
remote branch, eg with "checkout -b feature1 origin/master". With
the default branch.autosetupmerge configuration (value "true"), git
will automatically add origin/master as the upstream tracking branch.

When the user pushes with a default "git push", with the intention of
pushing their (new) topic branch to the remote, they get an error, and
(amongst other things) a suggestion to run "git push origin HEAD".

If they follow this suggestion the push succeeds, but on subsequent
default pushes they continue to get an error - so eventually they
figure out to add "-u" to change the tracking branch, or they spelunk
the push.default config doc as proposed and set it to "current", or
some GUI tooling does one or the other of these things for them.

When one of their coworkers later works on the same topic branch,
they don't get any of that "weirdness". They just "git checkout
feature1" and everything works exactly as they expect, with the shared
remote branch set up as remote tracking branch, and push and pull
working out of the box.

The "stable state" for this way of working is that local branches have
the same-name remote tracking branch (origin/feature1 in this
example), and multiple people can work on that remote feature branch
at the same time, trusting "git pull" to merge or rebase as required
for them to be able to push their interim changes to that same feature
branch on that same remote.

(merging from the upstream "master" branch, and merging back to it,
are separate more involved processes in this flow).

There is a problem in this flow/way of working, however, which is that
the first user, when they first branched from origin/master, ended up
with the "wrong" remote tracking branch (different from the stable
state). For a while, before they pushed (and maybe longer, if they
don't use -u/--set-upstream), their "git pull" wasn't getting other
users' changes to the feature branch - it was getting any changes from
the remote "master" branch instead (a completely different class of
changes!)

An experienced git user might say "well yeah, that's what it means to
have the remote tracking branch set to origin/master!" - but the
original user above didn't *ask* to have the remote master branch
added as remote tracking branch - that just happened automatically
when they branched their feature branch. They didn't necessarily even
notice or understand the meaning of the "set up to track 'origin/master'"
message when they created the branch - especially if they are using a
GUI.

Looking at how to fix this, you might think "OK, so disable auto setup
of remote tracking - set branch.autosetupmerge to false" - but that
will inconvenience the *second* user in this story - the one who just
wanted to start working on the topic branch. The first and second
users swap roles at different points in time of course - they should
both have a sane configuration that does the right thing in both
situations.

Make this "branches have the same name locally as on the remote"
workflow less painful / more obvious by introducing a new
branch.autosetupmerge option called "simple", to match the same-name
"push.default" option that makes similar assumptions.

This new option automatically sets up tracking in a *subset* of the
current default situations: when the original ref is a remote tracking
branch *and* has the same branch name on the remote (as the new local
branch name).

Update the error displayed when the 'push.default=simple' configuration
rejects a mismatching-upstream-name default push, to offer this new
branch.autosetupmerge option that will prevent this class of error.

With this new configuration, in the example situation above, the first
user does *not* get origin/master set up as the tracking branch for
the new local branch. If they "git pull" in their new local-only
branch, they get an error explaining there is no upstream branch -
which makes sense and is helpful. If they "git push", they get an
error explaining how to push *and* suggesting they specify
--set-upstream - which is exactly the right thing to do for them.

This new option is likely not appropriate for users intentionally
implementing a "triangular workflow" with a shared upstream tracking
branch, that they "git pull" in and a "private" feature branch that
they push/force-push to just for remote safe-keeping until they are
ready to push up to the shared branch explicitly/separately. Such
users are likely to prefer keeping the current default
merge.autosetupmerge=true behavior, and change their push.default to
"current".

Also extend the existing branch tests with three new cases testing
this option - the obvious matching-name and non-matching-name cases,
and also a non-matching-ref-type case. The matching-name case needs to
temporarily create an independent repo to fetch from, as the general
strategy of using the local repo as the remote in these tests
precludes locally branching with the same name as in the "remote".

Signed-off-by: Tao Klerks <tao@klerks.biz>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
7 files changed
tree: 3a319ef502b5bb5f1566e94ff2ce2ba1e865fb57
  1. .github/
  2. block-sha1/
  3. builtin/
  4. ci/
  5. compat/
  6. contrib/
  7. Documentation/
  8. ewah/
  9. git-gui/
  10. gitk-git/
  11. gitweb/
  12. mergetools/
  13. negotiator/
  14. perl/
  15. po/
  16. ppc/
  17. refs/
  18. reftable/
  19. sha1dc/
  20. sha256/
  21. t/
  22. templates/
  23. trace2/
  24. xdiff/
  25. .cirrus.yml
  26. .clang-format
  27. .editorconfig
  28. .gitattributes
  29. .gitignore
  30. .gitmodules
  31. .mailmap
  32. .tsan-suppressions
  33. abspath.c
  34. aclocal.m4
  35. add-interactive.c
  36. add-interactive.h
  37. add-patch.c
  38. advice.c
  39. advice.h
  40. alias.c
  41. alias.h
  42. alloc.c
  43. alloc.h
  44. apply.c
  45. apply.h
  46. archive-tar.c
  47. archive-zip.c
  48. archive.c
  49. archive.h
  50. attr.c
  51. attr.h
  52. banned.h
  53. base85.c
  54. bisect.c
  55. bisect.h
  56. blame.c
  57. blame.h
  58. blob.c
  59. blob.h
  60. bloom.c
  61. bloom.h
  62. branch.c
  63. branch.h
  64. builtin.h
  65. bulk-checkin.c
  66. bulk-checkin.h
  67. bundle.c
  68. bundle.h
  69. cache-tree.c
  70. cache-tree.h
  71. cache.h
  72. cbtree.c
  73. cbtree.h
  74. chdir-notify.c
  75. chdir-notify.h
  76. check-builtins.sh
  77. checkout.c
  78. checkout.h
  79. chunk-format.c
  80. chunk-format.h
  81. CODE_OF_CONDUCT.md
  82. color.c
  83. color.h
  84. column.c
  85. column.h
  86. combine-diff.c
  87. command-list.txt
  88. commit-graph.c
  89. commit-graph.h
  90. commit-reach.c
  91. commit-reach.h
  92. commit-slab-decl.h
  93. commit-slab-impl.h
  94. commit-slab.h
  95. commit.c
  96. commit.h
  97. common-main.c
  98. config.c
  99. config.h
  100. config.mak.dev
  101. config.mak.in
  102. config.mak.uname
  103. configure.ac
  104. connect.c
  105. connect.h
  106. connected.c
  107. connected.h
  108. convert.c
  109. convert.h
  110. copy.c
  111. COPYING
  112. credential.c
  113. credential.h
  114. csum-file.c
  115. csum-file.h
  116. ctype.c
  117. daemon.c
  118. date.c
  119. date.h
  120. decorate.c
  121. decorate.h
  122. delta-islands.c
  123. delta-islands.h
  124. delta.h
  125. detect-compiler
  126. diff-delta.c
  127. diff-lib.c
  128. diff-merges.c
  129. diff-merges.h
  130. diff-no-index.c
  131. diff.c
  132. diff.h
  133. diffcore-break.c
  134. diffcore-delta.c
  135. diffcore-order.c
  136. diffcore-pickaxe.c
  137. diffcore-rename.c
  138. diffcore-rotate.c
  139. diffcore.h
  140. dir-iterator.c
  141. dir-iterator.h
  142. dir.c
  143. dir.h
  144. editor.c
  145. entry.c
  146. entry.h
  147. environment.c
  148. environment.h
  149. exec-cmd.c
  150. exec-cmd.h
  151. fetch-negotiator.c
  152. fetch-negotiator.h
  153. fetch-pack.c
  154. fetch-pack.h
  155. fmt-merge-msg.c
  156. fmt-merge-msg.h
  157. fsck.c
  158. fsck.h
  159. fsmonitor--daemon.h
  160. fsmonitor-ipc.c
  161. fsmonitor-ipc.h
  162. fsmonitor-settings.c
  163. fsmonitor-settings.h
  164. fsmonitor.c
  165. fsmonitor.h
  166. fuzz-commit-graph.c
  167. fuzz-pack-headers.c
  168. fuzz-pack-idx.c
  169. generate-cmdlist.sh
  170. generate-configlist.sh
  171. generate-hooklist.sh
  172. gettext.c
  173. gettext.h
  174. git-add--interactive.perl
  175. git-archimport.perl
  176. git-bisect.sh
  177. git-compat-util.h
  178. git-curl-compat.h
  179. git-cvsexportcommit.perl
  180. git-cvsimport.perl
  181. git-cvsserver.perl
  182. git-difftool--helper.sh
  183. git-filter-branch.sh
  184. git-instaweb.sh
  185. git-merge-octopus.sh
  186. git-merge-one-file.sh
  187. git-merge-resolve.sh
  188. git-mergetool--lib.sh
  189. git-mergetool.sh
  190. git-p4.py
  191. git-quiltimport.sh
  192. git-request-pull.sh
  193. git-send-email.perl
  194. git-sh-i18n.sh
  195. git-sh-setup.sh
  196. git-submodule.sh
  197. git-svn.perl
  198. GIT-VERSION-GEN
  199. git-web--browse.sh
  200. git.c
  201. git.rc
  202. gpg-interface.c
  203. gpg-interface.h
  204. graph.c
  205. graph.h
  206. grep.c
  207. grep.h
  208. hash-lookup.c
  209. hash-lookup.h
  210. hash.h
  211. hashmap.c
  212. hashmap.h
  213. help.c
  214. help.h
  215. hex.c
  216. hook.c
  217. hook.h
  218. http-backend.c
  219. http-fetch.c
  220. http-push.c
  221. http-walker.c
  222. http.c
  223. http.h
  224. ident.c
  225. imap-send.c
  226. INSTALL
  227. iterator.h
  228. json-writer.c
  229. json-writer.h
  230. khash.h
  231. kwset.c
  232. kwset.h
  233. levenshtein.c
  234. levenshtein.h
  235. LGPL-2.1
  236. line-log.c
  237. line-log.h
  238. line-range.c
  239. line-range.h
  240. linear-assignment.c
  241. linear-assignment.h
  242. list-objects-filter-options.c
  243. list-objects-filter-options.h
  244. list-objects-filter.c
  245. list-objects-filter.h
  246. list-objects.c
  247. list-objects.h
  248. list.h
  249. ll-merge.c
  250. ll-merge.h
  251. lockfile.c
  252. lockfile.h
  253. log-tree.c
  254. log-tree.h
  255. ls-refs.c
  256. ls-refs.h
  257. mailinfo.c
  258. mailinfo.h
  259. mailmap.c
  260. mailmap.h
  261. Makefile
  262. match-trees.c
  263. mem-pool.c
  264. mem-pool.h
  265. merge-blobs.c
  266. merge-blobs.h
  267. merge-ort-wrappers.c
  268. merge-ort-wrappers.h
  269. merge-ort.c
  270. merge-ort.h
  271. merge-recursive.c
  272. merge-recursive.h
  273. merge.c
  274. mergesort.c
  275. mergesort.h
  276. midx.c
  277. midx.h
  278. name-hash.c
  279. notes-cache.c
  280. notes-cache.h
  281. notes-merge.c
  282. notes-merge.h
  283. notes-utils.c
  284. notes-utils.h
  285. notes.c
  286. notes.h
  287. object-file.c
  288. object-name.c
  289. object-store.h
  290. object.c
  291. object.h
  292. oid-array.c
  293. oid-array.h
  294. oidmap.c
  295. oidmap.h
  296. oidset.c
  297. oidset.h
  298. oidtree.c
  299. oidtree.h
  300. pack-bitmap-write.c
  301. pack-bitmap.c
  302. pack-bitmap.h
  303. pack-check.c
  304. pack-objects.c
  305. pack-objects.h
  306. pack-revindex.c
  307. pack-revindex.h
  308. pack-write.c
  309. pack.h
  310. packfile.c
  311. packfile.h
  312. pager.c
  313. parallel-checkout.c
  314. parallel-checkout.h
  315. parse-options-cb.c
  316. parse-options.c
  317. parse-options.h
  318. patch-delta.c
  319. patch-ids.c
  320. patch-ids.h
  321. path.c
  322. path.h
  323. pathspec.c
  324. pathspec.h
  325. pkt-line.c
  326. pkt-line.h
  327. preload-index.c
  328. pretty.c
  329. pretty.h
  330. prio-queue.c
  331. prio-queue.h
  332. progress.c
  333. progress.h
  334. promisor-remote.c
  335. promisor-remote.h
  336. prompt.c
  337. prompt.h
  338. protocol-caps.c
  339. protocol-caps.h
  340. protocol.c
  341. protocol.h
  342. prune-packed.c
  343. prune-packed.h
  344. quote.c
  345. quote.h
  346. range-diff.c
  347. range-diff.h
  348. reachable.c
  349. reachable.h
  350. read-cache.c
  351. README.md
  352. rebase-interactive.c
  353. rebase-interactive.h
  354. rebase.c
  355. rebase.h
  356. ref-filter.c
  357. ref-filter.h
  358. reflog-walk.c
  359. reflog-walk.h
  360. reflog.c
  361. reflog.h
  362. refs.c
  363. refs.h
  364. refspec.c
  365. refspec.h
  366. remote-curl.c
  367. remote.c
  368. remote.h
  369. replace-object.c
  370. replace-object.h
  371. repo-settings.c
  372. repository.c
  373. repository.h
  374. rerere.c
  375. rerere.h
  376. reset.c
  377. reset.h
  378. resolve-undo.c
  379. resolve-undo.h
  380. revision.c
  381. revision.h
  382. run-command.c
  383. run-command.h
  384. SECURITY.md
  385. send-pack.c
  386. send-pack.h
  387. sequencer.c
  388. sequencer.h
  389. serve.c
  390. serve.h
  391. server-info.c
  392. setup.c
  393. sh-i18n--envsubst.c
  394. sha1dc_git.c
  395. sha1dc_git.h
  396. shallow.c
  397. shallow.h
  398. shared.mak
  399. shell.c
  400. shortlog.h
  401. sideband.c
  402. sideband.h
  403. sigchain.c
  404. sigchain.h
  405. simple-ipc.h
  406. sparse-index.c
  407. sparse-index.h
  408. split-index.c
  409. split-index.h
  410. stable-qsort.c
  411. strbuf.c
  412. strbuf.h
  413. streaming.c
  414. streaming.h
  415. string-list.c
  416. string-list.h
  417. strmap.c
  418. strmap.h
  419. strvec.c
  420. strvec.h
  421. sub-process.c
  422. sub-process.h
  423. submodule-config.c
  424. submodule-config.h
  425. submodule.c
  426. submodule.h
  427. symlinks.c
  428. tag.c
  429. tag.h
  430. tar.h
  431. tempfile.c
  432. tempfile.h
  433. thread-utils.c
  434. thread-utils.h
  435. tmp-objdir.c
  436. tmp-objdir.h
  437. trace.c
  438. trace.h
  439. trace2.c
  440. trace2.h
  441. trailer.c
  442. trailer.h
  443. transport-helper.c
  444. transport-internal.h
  445. transport.c
  446. transport.h
  447. tree-diff.c
  448. tree-walk.c
  449. tree-walk.h
  450. tree.c
  451. tree.h
  452. unicode-width.h
  453. unimplemented.sh
  454. unix-socket.c
  455. unix-socket.h
  456. unix-stream-server.c
  457. unix-stream-server.h
  458. unpack-trees.c
  459. unpack-trees.h
  460. upload-pack.c
  461. upload-pack.h
  462. url.c
  463. url.h
  464. urlmatch.c
  465. urlmatch.h
  466. usage.c
  467. userdiff.c
  468. userdiff.h
  469. utf8.c
  470. utf8.h
  471. varint.c
  472. varint.h
  473. version.c
  474. version.h
  475. versioncmp.c
  476. walker.c
  477. walker.h
  478. wildmatch.c
  479. wildmatch.h
  480. worktree.c
  481. worktree.h
  482. wrap-for-bin.sh
  483. wrapper.c
  484. write-or-die.c
  485. ws.c
  486. wt-status.c
  487. wt-status.h
  488. xdiff-interface.c
  489. xdiff-interface.h
  490. zlib.c
README.md

Build status

Git - fast, scalable, distributed revision control system

Git is a fast, scalable, distributed revision control system with an unusually rich command set that provides both high-level operations and full access to internals.

Git is an Open Source project covered by the GNU General Public License version 2 (some parts of it are under different licenses, compatible with the GPLv2). It was originally written by Linus Torvalds with help of a group of hackers around the net.

Please read the file INSTALL for installation instructions.

Many Git online resources are accessible from https://git-scm.com/ including full documentation and Git related tools.

See Documentation/gittutorial.txt to get started, then see Documentation/giteveryday.txt for a useful minimum set of commands, and Documentation/git-<commandname>.txt for documentation of each command. If git has been correctly installed, then the tutorial can also be read with man gittutorial or git help tutorial, and the documentation of each command with man git-<commandname> or git help <commandname>.

CVS users may also want to read Documentation/gitcvs-migration.txt (man gitcvs-migration or git help cvs-migration if git is installed).

The user discussion and development of Git take place on the Git mailing list -- everyone is welcome to post bug reports, feature requests, comments and patches to git@vger.kernel.org (read Documentation/SubmittingPatches for instructions on patch submission and Documentation/CodingGuidelines).

Those wishing to help with error message, usage and informational message string translations (localization l10) should see po/README.md (a po file is a Portable Object file that holds the translations).

To subscribe to the list, send an email with just “subscribe git” in the body to majordomo@vger.kernel.org (not the Git list). The mailing list archives are available at https://lore.kernel.org/git/, http://marc.info/?l=git and other archival sites.

Issues which are security relevant should be disclosed privately to the Git Security mailing list git-security@googlegroups.com.

The maintainer frequently sends the “What's cooking” reports that list the current status of various development topics to the mailing list. The discussion following them give a good reference for project status, development direction and remaining tasks.

The name “git” was given by Linus Torvalds when he wrote the very first version. He described the tool as “the stupid content tracker” and the name as (depending on your mood):

  • random three-letter combination that is pronounceable, and not actually used by any common UNIX command. The fact that it is a mispronunciation of “get” may or may not be relevant.
  • stupid. contemptible and despicable. simple. Take your pick from the dictionary of slang.
  • “global information tracker”: you're in a good mood, and it actually works for you. Angels sing, and a light suddenly fills the room.
  • “goddamn idiotic truckload of sh*t”: when it breaks