Dereckson: Documentation by GPT-5.6-Sol for git bye / newbug and the new receive / resend / land new version

2026-08-23T04:29:07Z

Documentation by GPT-5.6-Sol for git bye / newbug and the new receive / resend / land new version

New page

== Introduction ==
A small set of custom Git commands for working with short-lived feature branches is added to $HOME/bin.

The commands implement a change-centric workflow inspired by Phabricator's <code>arc land</code> model and Gerrit:

* the default branch is the canonical project history;
* one feature branch represents one logical change;
* the feature commit may be amended while the change is under development;
* feature branches may be published to a remote for review, testing or deployment;
* once accepted, the change is landed on the default branch;
* feature branches are disposable and are removed after landing.

The normal lifecycle is:

<syntaxhighlight lang="text">
newbug → edit/commit → resend ↔ receive → land
↘
bye
</syntaxhighlight>

<code>land</code> is used when landing the change locally.

<code>bye</code> is used when the change has already been merged elsewhere, for example through a forge or code-review interface.

== Command reference ==

{| class="wikitable"
! Command
! Purpose
! Typical use
|-
| <code>git get-default-branch</code>
| Determine the repository's integration branch
| Used directly and by the other workflow commands
|-
| <code>git newbug BRANCH</code>
| Start a new change from an updated default branch
| Beginning a task
|-
| <code>git resend</code>
| Amend and republish the current feature commit
| Send a new revision for testing or review
|-
| <code>git receive</code>
| Replace the local feature checkout with its published version
| Development or deployment machine
|-
| <code>git land</code>
| Integrate the feature commit and clean up the branch
| Completing a locally landed change
|-
| <code>git bye</code>
| Return to the default branch and remove the feature branch
| Change already merged elsewhere
|-
| <code>git delete-remote-branch</code>
| Delete a branch from a remote repository
| Explicit remote branch cleanup
|}

== Philosophy ==

These commands deliberately use Git as a change-oriented version-control system.

The permanent artifact is the clean history of accepted changes on the default branch.

A feature branch is temporary infrastructure around one of those changes. While the change is being prepared, its commit can be amended and republished as many times as necessary.

Consequently:

* rewriting a private feature branch is normal;
* rewriting the default branch is not;
* feature branches are short-lived;
* intermediate correction commits do not need to survive forever;
* landing turns the final version of the change into permanent project history;
* local and remote feature branches can then be discarded.

This is closer to the change model used by Phabricator or Gerrit than to workflows where the complete development history of every feature branch is retained after merging.

== Git subcommands ==

The commands are installed as executables named <code>git-NAME</code> in the user's <code>PATH</code>.

Git automatically exposes such executables as subcommands.

For example:

<syntaxhighlight lang="console">
$ git get-default-branch
main
</syntaxhighlight>

invokes the <code>git-get-default-branch</code> executable.

== Typical workflow ==

=== Start a change ===

Start from the repository's default branch and create a new feature branch:

<syntaxhighlight lang="console">
$ git newbug fix-vault-policy
</syntaxhighlight>

<code>git newbug</code>:

# determines the repository's default branch;
# switches to it;
# updates it from the remote repository;
# creates the requested feature branch.

The resulting history is conceptually:

<syntaxhighlight lang="text">
A---B---C main
\
D fix-vault-policy
</syntaxhighlight>

The feature branch is intended to contain one logical change.

After editing files, create the initial commit normally:

<syntaxhighlight lang="console">
$ git add -p
$ git commit
</syntaxhighlight>

For example:

<syntaxhighlight lang="console">
$ git commit -m "vault: restrict access to production secrets"
</syntaxhighlight>

=== Amend and republish a change ===

During development, the commit may be updated instead of accumulating fixup commits.

Use:

<syntaxhighlight lang="console">
$ git resend
</syntaxhighlight>

The command interactively stages changes with:

<syntaxhighlight lang="console">
git add -p
</syntaxhighlight>

and amends the current commit while retaining its commit message.

The updated feature branch is then published.

If a remote named <code>datacube</code> exists, it is preferred:

<syntaxhighlight lang="text">
workstation
|
| git resend
v
datacube/fix-vault-policy
</syntaxhighlight>

Otherwise, the branch is pushed to <code>origin</code>.

Because amending a commit changes its object ID, publishing a new revision requires replacing the previously published feature-branch commit.

This rewriting is expected for short-lived feature branches. It must not be used to rewrite shared permanent branches such as <code>main</code>.

==== DevCentral repositories ====

For repositories hosted on DevCentral, <code>git resend</code> does not automatically push to <code>origin</code>.

Use Arcanist:

<syntaxhighlight lang="console">
$ arc diff
</syntaxhighlight>

or configure a <code>datacube</code> remote for the workstation-to-server sharing workflow.

=== Receive a published revision on another machine ===

A development or deployment machine can synchronize its current feature branch with the version published from the workstation:

<syntaxhighlight lang="console">
$ git receive
</syntaxhighlight>

The command fetches the remote repositories and then resets the current feature branch to:

<syntaxhighlight lang="text">
datacube/<current-branch>
</syntaxhighlight>

when <code>datacube</code> exists, or otherwise:

<syntaxhighlight lang="text">
origin/<current-branch>
</syntaxhighlight>

For example, after publishing a Salt change from the workstation:

<syntaxhighlight lang="console">
workstation$ git resend
</syntaxhighlight>

the development server can receive and test it:

<syntaxhighlight lang="console">
devserver$ git receive
devserver$ salt-call saltutil.sync_modules
</syntaxhighlight>

'''Warning:''' <code>git receive</code> uses <code>git reset --hard</code>.

Tracked changes in the index and working tree which are not present in the selected remote branch are discarded.

Untracked files are not removed.

The command is therefore intended for feature branches on development or deployment checkouts where the remote version is authoritative.

== Landing a change ==

When the feature commit is ready to become part of the repository's canonical history, run:

<syntaxhighlight lang="console">
$ git land
</syntaxhighlight>

The command:

# fetches remote changes;
# switches to the default branch;
# updates the default branch;
# cherry-picks the feature commit;
# pushes the updated default branch;
# deletes the local feature branch;
# deletes the published feature branch from <code>datacube</code>, or from <code>origin</code> when no <code>datacube</code> remote exists.

For example:

<syntaxhighlight lang="text">
Before:

A---B---C---E main
\
D' fix-vault-policy

git land

After:

A---B---C---E---D'' main
</syntaxhighlight>

The feature branch is then removed.

<code>D'</code> and <code>D''</code> represent the same logical change at different points of its Git history: cherry-picking creates a new commit on the default branch.

=== One change per branch ===

<code>git land</code> lands the commit at the tip of the current feature branch.

The workflow therefore expects a feature branch to represent one logical commit.

During review or testing, update that commit with:

<syntaxhighlight lang="console">
$ git resend
</syntaxhighlight>

rather than adding a succession of commits such as:

<syntaxhighlight lang="text">
Implement feature
Fix typo
Actually fix test
Address review
Fix lint
</syntaxhighlight>

Those intermediate states are useful while developing the change, but do not need to become part of the permanent project history.

== Cleaning up an externally merged branch ==

Sometimes the change is landed by another system, for example after merging a pull request or accepting a code review.

In that case, there is nothing left for <code>git land</code> to integrate.

From the feature branch, run:

<syntaxhighlight lang="console">
$ git bye
</syntaxhighlight>

The command switches back to the repository's default branch, updates it when appropriate, and deletes the previous local feature branch.

Example:

<syntaxhighlight lang="console">
$ git status --short --branch
## fix-vault-policy

$ git bye

$ git status --short --branch
## main...origin/main
</syntaxhighlight>

<code>git bye</code> force-deletes the local feature branch.

Use it only when the change has already been integrated elsewhere or when the local branch is deliberately no longer needed.

== Determining the default branch ==

Use:

<syntaxhighlight lang="console">
$ git get-default-branch
main
</syntaxhighlight>

The command determines the branch which should be treated as the repository's integration branch.

Examples include:

<syntaxhighlight lang="text">
main
master
production
dev
</syntaxhighlight>

Other workflow commands use this helper instead of assuming that every repository uses <code>main</code>.

For example:

<syntaxhighlight lang="console">
$ git get-default-branch
production

$ git newbug update-webserver
</syntaxhighlight>

will create <code>update-webserver</code> from <code>production</code>.

== Deleting a remote branch ==

A remote branch can be explicitly removed with:

<syntaxhighlight lang="console">
$ git delete-remote-branch origin old-feature
</syntaxhighlight>

which is equivalent to:

<syntaxhighlight lang="console">
$ git push origin --delete old-feature
</syntaxhighlight>

The current implementation also supports using only the branch name:

<syntaxhighlight lang="console">
$ git delete-remote-branch old-feature
</syntaxhighlight>

In that form, <code>origin</code> is used as the remote.

The historical default with no arguments is:

<syntaxhighlight lang="console">
$ git delete-remote-branch
</syntaxhighlight>

which deletes <code>origin/master</code>.

'''Warning:''' the zero-argument form is intended for historical <code>master</code>-to-<code>main</code> migration work. An explicit branch name should normally be provided.

== Remote selection ==

Some commands recognize a remote named <code>datacube</code>.

This remote is intended as an intermediate location for sharing work-in-progress branches between a workstation and development or deployment machines.

When <code>datacube</code> exists:

<syntaxhighlight lang="text">
workstation
|
| git resend
v
datacube
|
| git receive
v
development server
</syntaxhighlight>

Without <code>datacube</code>, the equivalent workflow uses <code>origin</code> where appropriate.

This separates two concepts:

* the repository hosting service used for permanent collaboration;
* an optional branch transport used to send a work-in-progress change to another machine.

User:Dereckson/Devserver/Git - Revision history

Dereckson: Documentation by GPT-5.6-Sol for git bye / newbug and the new receive / resend / land new version