User:Dereckson/Devserver/Git

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 arc land 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:

newbug → edit/commit → resend ↔ receive → land
                                     ↘
                                      bye

land is used when landing the change locally.

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

Command reference

Command	Purpose	Typical use
git get-default-branch	Determine the repository's integration branch	Used directly and by the other workflow commands
git newbug BRANCH	Start a new change from an updated default branch	Beginning a task
git resend	Amend and republish the current feature commit	Send a new revision for testing or review
git receive	Replace the local feature checkout with its published version	Development or deployment machine
git land	Integrate the feature commit and clean up the branch	Completing a locally landed change
git bye	Return to the default branch and remove the feature branch	Change already merged elsewhere
git delete-remote-branch	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 git-NAME in the user's PATH.

Git automatically exposes such executables as subcommands.

For example:

$ git get-default-branch
main

invokes the git-get-default-branch executable.

Typical workflow

Start a change

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

$ git newbug fix-vault-policy

git newbug:

1. determines the repository's default branch;
2. switches to it;
3. updates it from the remote repository;
4. creates the requested feature branch.

The resulting history is conceptually:

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

The feature branch is intended to contain one logical change.

After editing files, create the initial commit normally:

$ git add -p
$ git commit

For example:

$ git commit -m "vault: restrict access to production secrets"

Amend and republish a change

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

Use:

$ git resend

The command interactively stages changes with:

git add -p

and amends the current commit while retaining its commit message.

The updated feature branch is then published.

If a remote named datacube exists, it is preferred:

workstation
    |
    | git resend
    v
datacube/fix-vault-policy

Otherwise, the branch is pushed to origin.

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 main.

DevCentral repositories

For repositories hosted on DevCentral, git resend does not automatically push to origin.

Use Arcanist:

$ arc diff

or configure a datacube 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:

$ git receive

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

datacube/<current-branch>

when datacube exists, or otherwise:

origin/<current-branch>

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

workstation$ git resend

the development server can receive and test it:

devserver$ git receive
devserver$ salt-call saltutil.sync_modules

Warning: git receive uses git reset --hard.

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:

$ git land

The command:

1. fetches remote changes;
2. switches to the default branch;
3. updates the default branch;
4. cherry-picks the feature commit;
5. pushes the updated default branch;
6. deletes the local feature branch;
7. deletes the published feature branch from datacube, or from origin when no datacube remote exists.

For example:

Before:

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


git land


After:

A---B---C---E---D''  main

The feature branch is then removed.

D' and D 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

git land 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:

$ git resend

rather than adding a succession of commits such as:

Implement feature
Fix typo
Actually fix test
Address review
Fix lint

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 git land to integrate.

From the feature branch, run:

$ git bye

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

Example:

$ git status --short --branch
## fix-vault-policy

$ git bye

$ git status --short --branch
## main...origin/main

git bye 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:

$ git get-default-branch
main

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

Examples include:

main
master
production
dev

Other workflow commands use this helper instead of assuming that every repository uses main.

For example:

$ git get-default-branch
production

$ git newbug update-webserver

will create update-webserver from production.

Deleting a remote branch

A remote branch can be explicitly removed with:

$ git delete-remote-branch origin old-feature

which is equivalent to:

$ git push origin --delete old-feature

The current implementation also supports using only the branch name:

$ git delete-remote-branch old-feature

In that form, origin is used as the remote.

The historical default with no arguments is:

$ git delete-remote-branch

which deletes origin/master.

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

Remote selection

Some commands recognize a remote named datacube.

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

When datacube exists:

workstation
    |
    | git resend
    v
datacube
    |
    | git receive
    v
development server

Without datacube, the equivalent workflow uses origin 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.