Git Cookbook

This chapter describes the commands often used while working with git. In addition to these basic commands, please make sure you have read:

Modifying existing files

To modify existing files:

git add filename
git commit -m "CAUSEWAY-nnn: yada yada"

The git add command adds the changes to the file(s) to the git index (aka staging area). If you were to make subsequent changes to the file these would not be committed.

The git commit takes all the staged changes and commits them locally. Note that these changes are not shared public with Apache Causeway' central git repo.

You can combine these two commands using -am flag to git commit:

git commit -am "CAUSEWAY-nnn: yada yada"

Adding new files

To add a new file:

git add .
git commit -m "CAUSEWAY-nnn: yada yada"

Note that this sequence of commands is identical to modifying an existing file. However, it isn’t possible to combine the two steps using git commit -am; the git add is always needed when adding new files to the repo.

Deleting files

To delete a file:

git rm filename
git commit -m "CAUSEWAY-nnn: yada yada"

Renaming or moving files

To rename or move a file:

git mv filename newfilename
git commit -m "CAUSEWAY-nnn: yada yada"

Common Workflows

The contributing page describes the workflow for non-committers. The Git policy describes a workflow for Apache Causeway committers.

Backing up a local branch

If committing to a local branch, the changes are still just that: local, and run risk of a disk failure or other disaster.

To create a new, similarly named branch on the central repo, use:

git push -u origin branchname

Using gitk --all will show you this new branch, named origin/branchname.

Thereafter, you can push subsequent commits using simply:

git push

Doing this also allows others to collaborate on this branch, just as they would for master.

When, eventually, you have reintegrated this branch, you can delete the remote branch using:

git push origin --delete branchname

For more detail, see this stackoverflow post.

Quick change: stashing changes

If you are working on something but are not ready to commit, then use:

git stash

If you use gitk --all then you’ll see new commits are made that hold the current state of your working directory and staging area.

You can then, for example, pull down the latest changes using git pull --rebase (see above).

To reapply your stash, then use:

git stash pop

Note that stashing works even if switching branches

Ignoring files

Put file patterns into .gitignore. There is one at the root of the git repo, but they can additionally appear in subdirectories (the results are cumulative).

More advanced use cases

If accidentally push to remote

Suppose you committed to master, and then pushed the change, and then decided that you didn’t intend to do that:

C1  -  C2  -  C3  -  C4  -  C5  -  C6  -  C7
                                          ^
                                          master
                                          ^
                                          origin/master

To go back to an earlier commit, first we wind back the local master:

git reset --hard C5

where C5 is the long sha-id for that commit.

This gets us to:

C1  -  C2  -  C3  -  C4  -  C5  -  C6  -  C7
                            ^
                            master
                                          ^
                                          origin/master

Then, do a force push:

git push origin master --force

If this doesn’t work, it may be that the remote repo has disabled this feature. There are other hacks to get around this, see for example here.

If you’ve accidentally worked on `master` branch

If at any time the git pull from your upstream fails, it most likely means that you must have made commits on the master branch. You can use gitk --all to confirm; at some point in time both master and origin\master will have a common ancestor.

You can retrospectively create a topic branch for the work you’ve accidentally done on master.

First, create a branch for your current commit:

git branch newbranch

Next, make sure you have no outstanding edits. If you do, you should commit them or stash them:

git stash

Finally, locate the shaId of the commit you want to roll back to (easily obtained in gitk -all), and wind master branch back to that commit:

git checkout master
git reset --hard shaId (1)

1	move master branch shaId of common ancestor