This page 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 "ISIS-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 Isis' central git repo.

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

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

Adding new files

To add a new file:

git add .
git commit -m "ISIS-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 "ISIS-nnn: yada yada"

Renaming or moving files

To rename or move a file:

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

Common Workflows (Committers only)

The contributing page describes the workflow for non-committers. This section is therefore primarily for the benefit of Isis committers.

Working on master

The easiest way of working is to make your commits directly on your local master. This is perhaps somewhat hacky, but acceptable for very small changes.

When you are ready to push your changes, use:

git pull --rebase

This will bring down all the latest commits made to the central repo, and update origin/master. It will then apply all commits made in your master branch on top of that.

Alternatively, you can do this in two stages:

git fetch                
git rebase origin/master

After the git fetch, you will see that gitk --all shows the new set of commits as a branch separate from your own commits on branch. The git rebase command then applies all your changes on top of that branch. (Your original commits are orphaned and are eventually garbage collected by git).

Once you're happy with all your changes, push your local repository onto the central repo:

git push

Creating a local branch

If you are working on a branch for a significant period (eg to implement a ticket), then it probably makes sense to create a local branch:

git checkout -b branchname

If you use gitk --all, then you'll see a new tag for the current commit. The command line in the shell also changes.

Any commits made now advance the new branch, but leave the master branch alone.

If you want to switch to some other branch, use:

git checkout branchname

Any changes in your working directory and index/staging area are preserved. This makes it easy to separate out different strands of work... you realize that some set of changes just made should be on a different ticket, so you create a new branch and commit those changes there.

Updating branch with latest

When you want to 'catch-up' with the changes made by others and in the remote origin, use:

git checkout branchname
git rebase master

This will reapply the commits from origin on top of the master branch. If there are conflicts then they will occur a this point. Conflicts are resolved by editing the file, then:

git add filename
git rebase --continue

Once the rebase is finished, you'll see the branch branchname as a direct descendent of master (use gitk --all to confirm). You will still be on the branchname. To catch up master, use:

git checkout master
git merge branchname --ff-only

The --ff-only ensures that the merge is a fast-forward; ie all commits will have only a single parent, and no conflicts.

At this point you can delete the branch:

git branch -d branchname

Push the changes

Immediately prior to pushing your changes, check one more time that you are up-to-date:

git fetch

If this pulls down any commits, then reintegrate first (using git rebase) and try again.

Assuming that now new commits were brought down, you can now simply do a fast forward merge of master, and then push the changes:

git checkout master
git merge --ff-only ISIS-123-blobs
git push

Because the master branch is a direct ancestor of the topic branch, the fast-forward merge should work. The git push then pushes those changes back to the master Isis repo.

To clean up, you can delete your topic branch:

git branch -d ISIS-123-blobs

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 these blogs/posts here and here.

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

See also:

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      # move master branch shaId of common ancestor

If you've forgotten to prefix your commits (but not pushed)

One of our committers, Alexander Krasnukhin, has put together some git scripts to help his workflow. Using one of these, git prefix, you:

can just commit with proper message without bothering about prefix and add prefix only in the end before the final push.

For example, to prefix all not yet prefixed commits master..isis/666 with ISIS-666 prefix, use:

  git prefix ISIS-666 master..isis/666

You can grab this utility, and others, from this repo.