mirror of
https://github.com/git/git
synced 2024-08-27 19:49:21 +00:00
![Tao Klerks](/assets/img/avatar_default.png)
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>
160 lines
5.3 KiB
C
160 lines
5.3 KiB
C
#ifndef BRANCH_H
|
|
#define BRANCH_H
|
|
|
|
struct repository;
|
|
struct strbuf;
|
|
|
|
enum branch_track {
|
|
BRANCH_TRACK_UNSPECIFIED = -1,
|
|
BRANCH_TRACK_NEVER = 0,
|
|
BRANCH_TRACK_REMOTE,
|
|
BRANCH_TRACK_ALWAYS,
|
|
BRANCH_TRACK_EXPLICIT,
|
|
BRANCH_TRACK_OVERRIDE,
|
|
BRANCH_TRACK_INHERIT,
|
|
BRANCH_TRACK_SIMPLE,
|
|
};
|
|
|
|
extern enum branch_track git_branch_track;
|
|
|
|
/* Functions for acting on the information about branches. */
|
|
|
|
/**
|
|
* Sets branch.<new_ref>.{remote,merge} config settings such that
|
|
* new_ref tracks orig_ref according to the specified tracking mode.
|
|
*
|
|
* - new_ref is the name of the branch that we are setting tracking
|
|
* for.
|
|
*
|
|
* - orig_ref is the name of the ref that is 'upstream' of new_ref.
|
|
* orig_ref will be expanded with DWIM so that the config settings
|
|
* are in the correct format e.g. "refs/remotes/origin/main" instead
|
|
* of "origin/main".
|
|
*
|
|
* - track is the tracking mode e.g. BRANCH_TRACK_REMOTE causes
|
|
* new_ref to track orig_ref directly, whereas BRANCH_TRACK_INHERIT
|
|
* causes new_ref to track whatever orig_ref tracks.
|
|
*
|
|
* - quiet suppresses tracking information.
|
|
*/
|
|
void dwim_and_setup_tracking(struct repository *r, const char *new_ref,
|
|
const char *orig_ref, enum branch_track track,
|
|
int quiet);
|
|
|
|
/*
|
|
* Creates a new branch, where:
|
|
*
|
|
* - r is the repository to add a branch to
|
|
*
|
|
* - name is the new branch name
|
|
*
|
|
* - start_name is the name of the existing branch that the new branch should
|
|
* start from
|
|
*
|
|
* - force enables overwriting an existing (non-head) branch
|
|
*
|
|
* - clobber_head_ok, when enabled with 'force', allows the currently
|
|
* checked out (head) branch to be overwritten
|
|
*
|
|
* - reflog creates a reflog for the branch
|
|
*
|
|
* - quiet suppresses tracking information
|
|
*
|
|
* - track causes the new branch to be configured to merge the remote branch
|
|
* that start_name is a tracking branch for (if any).
|
|
*
|
|
* - dry_run causes the branch to be validated but not created.
|
|
*
|
|
*/
|
|
void create_branch(struct repository *r,
|
|
const char *name, const char *start_name,
|
|
int force, int clobber_head_ok,
|
|
int reflog, int quiet, enum branch_track track,
|
|
int dry_run);
|
|
|
|
/*
|
|
* Creates a new branch in a repository and its submodules (and its
|
|
* submodules, recursively). The parameters are mostly analogous to
|
|
* those of create_branch() except for start_name, which is represented
|
|
* by two different parameters:
|
|
*
|
|
* - start_commitish is the commit-ish, in repository r, that determines
|
|
* which commits the branches will point to. The superproject branch
|
|
* will point to the commit of start_commitish and the submodule
|
|
* branches will point to the gitlink commit oids in start_commitish's
|
|
* tree.
|
|
*
|
|
* - tracking_name is the name of the ref, in repository r, that will be
|
|
* used to set up tracking information. This value is propagated to
|
|
* all submodules, which will evaluate the ref using their own ref
|
|
* stores. If NULL, this defaults to start_commitish.
|
|
*
|
|
* When this function is called on the superproject, start_commitish
|
|
* can be any user-provided ref and tracking_name can be NULL (similar
|
|
* to create_branches()). But when recursing through submodules,
|
|
* start_commitish is the plain gitlink commit oid. Since the oid cannot
|
|
* be used for tracking information, tracking_name is propagated and
|
|
* used for tracking instead.
|
|
*/
|
|
void create_branches_recursively(struct repository *r, const char *name,
|
|
const char *start_commitish,
|
|
const char *tracking_name, int force,
|
|
int reflog, int quiet, enum branch_track track,
|
|
int dry_run);
|
|
/*
|
|
* Check if 'name' can be a valid name for a branch; die otherwise.
|
|
* Return 1 if the named branch already exists; return 0 otherwise.
|
|
* Fill ref with the full refname for the branch.
|
|
*/
|
|
int validate_branchname(const char *name, struct strbuf *ref);
|
|
|
|
/*
|
|
* Check if a branch 'name' can be created as a new branch; die otherwise.
|
|
* 'force' can be used when it is OK for the named branch already exists.
|
|
* Return 1 if the named branch already exists; return 0 otherwise.
|
|
* Fill ref with the full refname for the branch.
|
|
*/
|
|
int validate_new_branchname(const char *name, struct strbuf *ref, int force);
|
|
|
|
/*
|
|
* Remove information about the merge state on the current
|
|
* branch. (E.g., MERGE_HEAD)
|
|
*/
|
|
void remove_merge_branch_state(struct repository *r);
|
|
|
|
/*
|
|
* Remove information about the state of working on the current
|
|
* branch. (E.g., MERGE_HEAD)
|
|
*/
|
|
void remove_branch_state(struct repository *r, int verbose);
|
|
|
|
/*
|
|
* Configure local branch "local" as downstream to branch "remote"
|
|
* from remote "origin". Used by git branch --set-upstream.
|
|
* Returns 0 on success.
|
|
*/
|
|
#define BRANCH_CONFIG_VERBOSE 01
|
|
int install_branch_config(int flag, const char *local, const char *origin, const char *remote);
|
|
|
|
/*
|
|
* Read branch description
|
|
*/
|
|
int read_branch_desc(struct strbuf *, const char *branch_name);
|
|
|
|
/*
|
|
* Check if a branch is checked out in the main worktree or any linked
|
|
* worktree and die (with a message describing its checkout location) if
|
|
* it is.
|
|
*/
|
|
void die_if_checked_out(const char *branch, int ignore_current_worktree);
|
|
|
|
/*
|
|
* Update all per-worktree HEADs pointing at the old ref to point the new ref.
|
|
* This will be used when renaming a branch. Returns 0 if successful, non-zero
|
|
* otherwise.
|
|
*/
|
|
int replace_each_worktree_head_symref(const char *oldref, const char *newref,
|
|
const char *logmsg);
|
|
|
|
#endif
|