| [ << Working with source code ] | [Top][Contents] | [ Compiling >> ] |
| [ < Configuring Git ] | [ Up : Working with source code ] | [ > ] |
3.2 Git cheat sheet
The intent of this section is to get you working on LilyPond quickly. If you want to learn about Git, go read Further Git documentation resources.
Also, these instructions are designed to eliminate the most common problems we have found in using Git. If you already know Git and have a different way of working, great! Feel free to ignore this advice.
| [ << Working with source code ] | [Top][Contents] | [ Compiling >> ] |
| [ < Git cheat sheet ] | [ Up : Git cheat sheet ] | [ > ] |
Pulling recent changes
As LilyPond’s source code is continously improved, it is wise to
integrate recent changes into your local copy whenever you start a
working session. On the master branch (this term is explained
below), run:
git pull
| [ << Working with source code ] | [Top][Contents] | [ Compiling >> ] |
| [ < ] | [ Up : Git cheat sheet ] | [ > ] |
Viewing the history
Each change is contained in a commit with an explanatory message. To list commits starting from the latest:
git log
Press <Enter> to see more or <Q> to exit.
Start work: make a new branch
The Git workflow is based on branches, which can be viewed as different copies of the source code with concurrent changes that are eventually merged. You start a contribution by creating a branch, freezing the initial state of the source code you will base your work onto. Ultimately, your branch will be merged in master. This latter special branch centralizes all features developed simultaneously and is the source for unstable releases.
Note: Remember, never directly commit to master.
Let’s pretend you want to add a section to the Contributor’s Guide about using branches. To create a new branch for this:
git branch cg-add-branches
| [ << Working with source code ] | [Top][Contents] | [ Compiling >> ] |
| [ < ] | [ Up : Git cheat sheet ] | [ > ] |
Switching branches
Switching branches is somehow like “loading a file”, although in this
case it is really “loading a directory and subdirectories full of
files”. The command to use is git switch1
git switch master git switch cg-add-branches git switch origin/release/unstable
Branches that begin with origin/ are part of the remote
repository, rather than your local repository, so when you check them
out you get a temporary local branch. Therefore, do not commit to
these either. Always work in a local branch.
| [ << Working with source code ] | [Top][Contents] | [ Compiling >> ] |
| [ < ] | [ Up : Git cheat sheet ] | [ > ] |
Listing branches
To list local branches:
git branch
If you want remote branches too:
git branch -a
In the output, the current branch is prefixed with a star.
| [ << Working with source code ] | [Top][Contents] | [ Compiling >> ] |
| [ < ] | [ Up : Git cheat sheet ] | [ > ] |
Staging and committing files
Now edit files. To show a summary of your edits:
git status
For every file that you modified or added, first preview your changes:
git diff file
If everything looks right:
git add file
Then commit your changes:
git commit
A text editor window appears for you to write a commit message. See Writing good commit messages.
| [ << Working with source code ] | [Top][Contents] | [ Compiling >> ] |
| [ < ] | [ Up : Git cheat sheet ] | [ > ] |
Amending and reverting changes
To add some more changes to the latest commit, stage them using
git add, then run:
git commit --amend
This also works for rephrasing the commit message.
To revert changes to a file that has not been committed yet, use
git restore2:
git restore filename
To get back to the last commit, discarding all changes:
git reset --hard HEAD
If the commit to edit is not the top one, you need to perform an
interactive rebase with git rebase -i $(git
merge-base master HEAD). The full functionality of git
rebase -i is not covered here; please try it and follow Git’s
instructions or read any tutorial on the Web.
| [ << Working with source code ] | [Top][Contents] | [ Compiling >> ] |
| [ < ] | [ Up : Git cheat sheet ] | [ > ] |
Uploading your branch for review
To upload the current branch on the remote repository:
git push -u fork cg-add-branches
This sets the remote branch so subsequent pushes are simpler:
git push
The next section covers how to create a merge request from your branch.
In response to review comments, you may need to amend your
changes. Do not close your merge request and open a new
one; instead, amend your commits, which can be done with git
commit --amend or git rebase -i as explained above. Note
that Git will by default refuse a push when you have amended your
commits. This is because this kind of push is a destructive
operation: once it is done, the old commits are no longer
available on the remote branch. Git prevents this as a safety
measure against deleting commits added by someone else without you
realizing it. Do not follow Git’s advice to do git pull
(which would try to integrate the remote changes into the local
ones); instead, just force it with
git push --force-with-lease
Also note that due to the way GitLab compares successive revisions
of a merge request, it is preferable if you do not mix catching up
with master and changing your commits. In other words, use
git rebase -i $(git merge-base master HEAD) rather than
git rebase -i master. Alternatively, first rebase on
master and push, then do the interactive rebase and push
again.
| [ << Working with source code ] | [Top][Contents] | [ Compiling >> ] |
| [ < ] | [ Up : Git cheat sheet ] | [ Lifecycle of a merge request > ] |
Deleting branches
After the merge request has passed testing and was merged to
master, or after a failed experiment, you can delete your
local branch.
git switch master git branch -d cg-add-branches
As a safety measure, this will fail if the commits of
cg-add-branches are not present in master. This can be
because you used GitLab to rebase your branch, which modifies the commit
data and changes the hash. If you are sure that the branch is not needed
anymore, replace the -d on the final line with a -D instead.
Over time, remote branches of accepted merge requests may accumulate in your local repository. If you want to delete these and get back to the state of the official repository, run
git fetch -p origin
(short for --prune) once in a while.
Footnotes
[1] If you are
using an outdated version of Git (older than 2.23), you need to use
git checkout instead.
[2] If you are using an outdated version of Git
(older than 2.23), you need to use git checkout instead.
| [ << Working with source code ] | [Top][Contents] | [ Compiling >> ] |
| [ < ] | [ Up : Git cheat sheet ] | [ Lifecycle of a merge request > ] |