Using Git as you work¶
Know what branch you’re working on¶
When using Git, it’s important to know which branch you currently have checked out because most git commands implicitly operate on the current branch. You can determine the currently checked out branch several ways.
One way is with git status:
$ git status On branch issue-demo nothing to commit, working directory clean
Another is with git branch which will display all local branches, with a star next to the current branch:
$ git branch * issue-demo main
To see even more information about your branches, including remote branches,
git branch -vva:
$ git branch -vva * issue-123 517468b troubleshooting tip about provisioning main f0eaee6 [origin/main] bug: Fix traceback in get_missed_message_token_from_address(). remotes/origin/HEAD -> origin/main remotes/origin/issue-1234 4aeccb7 Another test commit, with longer message. remotes/origin/main f0eaee6 bug: Fix traceback in get_missed_message_token_from_address(). remotes/upstream/main dbeab6a Optimize checks of test database state by moving into Python.
Keep your fork up to date¶
You’ll want to keep your fork up-to-date with changes from Zulip’s main repositories.
Note about git pull: You might be used to using
git pull on other
projects. With Zulip, because we don’t use merge commits, you’ll want to avoid
it. Rather than using
git pull, which by default is a shortcut for
git fetch && git merge FETCH_HEAD (docs), you
git fetch and then
First, fetch changes from Zulip’s upstream repository you configured in the step above:
$ git fetch upstream
Next, check out your
main branch and rebase it on top
$ git checkout main Switched to branch 'main' $ git rebase upstream/main
This will rollback any changes you’ve made to
main, update it from
upstream/main, and then re-apply your changes. Rebasing keeps the commit
history clean and readable.
When you’re ready, push your changes to your remote fork.
Make sure you’re in branch
main and then run
$ git checkout main $ git push origin main
You can keep any branch up to date using this method. If you’re working on a
feature branch (see next section), which we recommend, you would change the
command slightly, using the name of your
feature-branch rather than
$ git checkout feature-branch Switched to branch 'feature-branch' $ git rebase upstream/main $ git push origin feature-branch
Work on a feature branch¶
One way to keep your work organized is to create a branch for each issue or feature. Recall from how Git is different that Git is designed for lightweight branching and merging. You can and should create as many branches as you’d like.
First, make sure your
main branch is up-to-date with Zulip upstream (see
Next, from your
main branch, create a new tracking branch, providing a
descriptive name for your feature branch:
$ git checkout main Switched to branch 'main' $ git checkout -b issue-1755-fail2ban Switched to a new branch 'issue-1755-fail2ban'
Alternatively, you can create a new branch explicitly based off
$ git checkout -b issue-1755-fail2ban upstream/main Switched to a new branch 'issue-1755-fail2ban'
Now you’re ready to work on the issue or feature.
Run linters and tests locally¶
In addition to having GitHub Actions run tests and linters each time you push a new commit, you can also run them locally. See testing for details.
Recall that files tracked with Git have possible three states: committed, modified, and staged.
To prepare a commit, first add the files with changes that you want to include in your commit to your staging area. You add both new files and existing ones. You can also remove files from staging when necessary.
Get status of working directory¶
To see what files in the working directory have changes that have not been
If you have no changes in the working directory, you’ll see something like this:
$ git status On branch issue-123 nothing to commit, working directory clean
If you have unstaged changes, you’ll see something like this:
On branch issue-123 Untracked files: (use "git add <file>..." to include in what will be committed) newfile.py nothing added to commit but untracked files present (use "git add" to track)
Stage additions with git add¶
To add changes to your staging area, use
git add <filename>. Because
git add is all about staging the changes you want to commit, you use
it to add new files as well as files with changes to your staging
Continuing our example from above, after we run
git add newfile.py, we’ll see
the following from
On branch issue-123 Changes to be committed: (use "git reset HEAD <file>..." to unstage) new file: newfile.py
You can view the changes in files you have staged with
git diff --cached. To
view changes to files you haven’t yet staged, just use
If you want to add all changes in the working directory, use
git add -A
You can also stage changes using your graphical Git client.
If you stage a file, you can undo it with
git reset HEAD <filename>. Here’s
an example where we stage a file
test3.txt and then unstage it:
$ git add test3.txt On branch issue-1234 Changes to be committed: (use "git reset HEAD <file>..." to unstage) new file: test3.txt $ git reset HEAD test3.txt $ git status On branch issue-1234 Untracked files: (use "git add <file>..." to include in what will be committed) test3.txt nothing added to commit but untracked files present (use "git add" to track)
Stage deletions with git rm¶
To remove existing files from your repository, use
(documentation). This command can either stage the file for
removal from your repository AND delete it from your working directory or just
stage the file for deletion and leave it in your working directory.
To stage a file for deletion and remove it from your working directory, use
git rm <filename>:
$ git rm test.txt rm 'test.txt' $ git status On branch issue-1234 Changes to be committed: (use "git reset HEAD <file>..." to unstage) deleted: test.txt $ ls test.txt ls: No such file or directory
To stage a file for deletion and keep it in your working directory, use
git rm --cached <filename>:
$ git rm --cached test2.txt rm 'test2.txt' $ git status On branch issue-1234 Changes to be committed: (use "git reset HEAD <file>..." to unstage) deleted: test2.txt $ ls test2.txt test2.txt
If you stage a file for deletion with the
--cached option, and haven’t yet
git commit, you can undo it with
git reset HEAD <filename>:
$ git reset HEAD test2.txt
Unfortunately, you can’t restore a file deleted with
git rm if you didn’t use
--cache option. However,
git rm only deletes files it knows about.
Files you have never added to git won’t be deleted.
When you’ve staged all your changes, you’re ready to commit. You can do this
git commit -m "My commit message." to include a commit message.
Here’s an example of committing with the
-m for a one-line commit message:
$ git commit -m "Add a test commit for docs." [issue-123 173e17a] Add a test commit for docs. 1 file changed, 1 insertion(+) create mode 100644 newfile.py
You can also use
git commit without the
-m option and your editor to open,
allowing you to easily draft a multi-line commit message.
How long your commit message should be depends on where you are in your work. Using short, one-line messages for commits related to in-progress work makes sense. For a commit that you intend to be final or that encompasses a significant amount or complex work, you should include a longer message.
Here’s an example of a longer commit message that will be used for a pull request:
Integrate Fail2Ban. Updates Zulip logging to put an unambiguous entry into the logs such that fail2ban can be configured to look for these entries. Tested on my local Ubuntu development server, but would appreciate someone testing on a production install with more users. Fixes #1755.
The first line is the summary. It’s a complete sentence, ending in a period. It uses a present-tense action verb, “Integrate”, rather than “Integrates” or “Integrating”.
The following paragraphs are full prose and explain why and how the change was made. It explains what testing was done and asks specifically for further testing in a more production-like environment.
The final paragraph indicates that this commit addresses and fixes issue #1755.
When you submit your pull request, GitHub will detect and link this reference
to the appropriate issue. Once your commit is merged into
will automatically close the referenced issue. See Closing issues via commit
messages for details.
Note in particular that GitHub’s regular expressions for this feature
are sloppy, so phrases like
Partially fixes #1234 will automatically
close the issue. Phrases like
Fixes part of #1234 are a good
Make as many commits as you need to to address the issue or implement your feature.
Push your commits to GitHub¶
As you’re working, it’s a good idea to frequently push your changes to GitHub. This ensures your work is backed up should something happen to your local machine and allows others to follow your progress. It also allows you to work from multiple computers without losing work.
Pushing to a feature branch is just like pushing to
$ git push origin <branch-name> Counting objects: 6, done. Delta compression using up to 4 threads. Compressing objects: 100% (4/4), done. Writing objects: 100% (6/6), 658 bytes | 0 bytes/s, done. Total 6 (delta 3), reused 0 (delta 0) remote: Resolving deltas: 100% (3/3), completed with 1 local objects. To email@example.com:christi3k/zulip.git * [new branch] issue-demo -> issue-demo
If you want to see what git will do without actually performing the push, add
-n (dry-run) option:
git push -n origin <branch-name>. If everything
looks good, re-run the push command without
If the feature branch does not already exist on GitHub, it will be created when
you push and you’ll see
* [new branch] in the command output.
Examine and tidy your commit history¶
Examining your commit history prior to submitting your pull request is a good idea. Is it tidy such that each commit represents a minimally coherent idea (see commit discipline)? Do your commit messages follow Zulip’s style? Will the person reviewing your commit history be able to clearly understand your progression of work?
On the command line, you can use the
git log command to display an easy to
read list of your commits:
$ git log --all --graph --oneline --decorate * 4f8d75d (HEAD -> 1754-docs-add-git-workflow) docs: Add details about configuring Travis CI. * bfb2433 (origin/1754-docs-add-git-workflow) docs: Add section for keeping fork up-to-date to Git Guide. * 4fe10f8 docs: Add sections for creating and configuring fork to Git Guide. * 985116b docs: Add graphic client recs to Git Guide. * 3c40103 docs: Add stubs for remaining Git Guide sections. * fc2c01e docs: Add git guide quickstart. | * f0eaee6 (upstream/main) bug: Fix traceback in get_missed_message_token_from_address().
Alternatively, use your graphical client to view the history for your feature branch.
If you need to update any of your commits, you can do so with an interactive rebase. Common reasons to use an interactive rebase include:
squashing several commits into fewer commits
splitting a single commit into two or more
rewriting one or more commit messages
There is ample documentation on how to rebase, so we won’t go into details here. We recommend starting with GitHub’s help article on rebasing and then consulting Git’s documentation for git-rebase if you need more details.
If all you need to do is edit the commit message for your last commit, you can
do that with
git commit --amend. See Git Basics - Undoing
Things for details on this and other useful commands.
Force-push changes to GitHub after you’ve altered your history¶
Any time you alter history for commits you have already pushed to GitHub,
you’ll need to prefix the name of your branch with a
+. Without this, your
updates will be rejected with a message such as:
$ git push origin 1754-docs-add-git-workflow To firstname.lastname@example.org:christi3k/zulip.git ! [rejected] 1754-docs-add-git-workflow -> 1754-docs-add-git-workflow (non-fast-forward) error: failed to push some refs to 'email@example.com:christi3k/zulip.git' hint: Updates were rejected because the tip of your current branch is behind hint: its remote counterpart. Integrate the remote changes (e.g. hint: 'git pull ...') before pushing again. hint: See the 'Note about fast-forwards' in 'git push --help' for details.
Re-running the command with
+<branch> allows the push to continue by
re-writing the history for the remote repository:
$ git push origin +1754-docs-add-git-workflow Counting objects: 12, done. Delta compression using up to 4 threads. Compressing objects: 100% (12/12), done. Writing objects: 100% (12/12), 3.71 KiB | 0 bytes/s, done. Total 12 (delta 8), reused 0 (delta 0) remote: Resolving deltas: 100% (8/8), completed with 2 local objects. To firstname.lastname@example.org:christi3k/zulip.git + 2d49e2d...bfb2433 1754-docs-add-git-workflow -> 1754-docs-add-git-workflow (forced update)
This is perfectly okay to do on your own feature branches, especially if you’re the only one making changes to the branch. If others are working along with you, they might run into complications when they retrieve your changes because anyone who has based their changes off a branch you rebase will have to do a complicated rebase.