If you're planning to edit a currently existing file, open that file, from within your local copy of the repo, into an appropriate editor and make your changes. If you're planning on adding a new file, create, edit, and save that file into the correct directory inside your local copy of the repo. Once you've made a set of changes, it's time to commit.
A commit is a save point in your project. It's similar to saving a file to your computer, however, instead of overwriting the previous save, it creates a timeline of save points. You can return to a previous save point at any time.
To best be able to utilise commits, you need to make them often. Lots of little commits creates many "undo" points in your project. This way, if you head down the wrong track or find your changes aren't working, you can easily return to the last known-good point and work from there.
As well, you can use committing often to divide up your set of changes. Consider a commit to be a complete and distinct idea. Each time you complete a concept you wanted to change, commit. The sum of these commits will be a combination of all the changes you intend to submit to the final project. This creates a timeline for your set of changes and allows for a better understanding of what your train of thought was while you were completing them. This can make it easier for you to make changes later, and easier for a reviewer to see where you were going with your ideas.
The first thing you want to do when you're ready to commit, is check the
git status is Your Best Friend
When inside your repo, before you run any commands, you always want to run
git status. This provides you with the state of your changes. Knowing the current status can help you know what command to run next. For example, If you have
Changes not staged for commit: the next command you may want to run is
git add to add your changes to be committed. If you have
Changes to be committed:, the next thing you may want to do is run
git commit to commit your changes. Don't worry, we'll cover all of this!
The important thing is to run
git status every time before you run anything else so you know where you are.
It's time for your first commit. The first thing you'll do is run
As you can see, I've modified the express.py file. It's listed under
Changes not staged for commit:. Before I go any further, I'd like to make sure I've made all of the changes I intended to. So, I'm going to run
git diff compares two states of the file. The first state is the original state if this is your first time editing it or the state since the last commit if you've already made a series of commits. The second state is the current state including your changes. It provides a color coded look at the difference between the two files, which highlights all the changes you've made. It only shows you the code near your changes - some files are extremely large and it would take forever to scroll through the entire file to look at a small change. Be aware, there are times when you'll make many changes, and the results of
git diff will take a long time to go through.
To see your changes, enter the
git diff command.
I've added three lines of code. These are the green lines denoted with a plus sign at the beginning of the line. These are all the changes I'd like to make for now. So I'm certain I'm ready commit.
It's always a good idea to run
Remember, my file is still listed as
Changes not staged for commit:. This means before I can commit it, I must use
To prepare a changed file to be committed, you must run
git add adds the file to the list of files to be committed. You can add as many changed files as you like to that list.
To add your file to the list, enter the
git add command:
Followed by, you guessed it,
You'll see that you now have
Changes to be committed:. Any files under this list will be added to the current commit. The only file I have listed is express.py because that's the only file I've changed. Since that's the only file I'm planning to add, I'm ready to commit.
When you commit, you'll enter a commit message. This message is a short description of the change you're committing. It should be 72 characters or less. If you're committing a new file for the first time, it's common practice to use the commit message,
"Initial commit.". Otherwise, it can be whatever you like.
To commit your file, enter the following command, replacing
Commit message with your commit message:
git commit -m "Commit message"
If you made a significant number of changes, you may want to leave a longer commit message. You'll want to setup Git to use your editor of choice by following the instructions found here. Typically it defaults to vim. Windows users will probably want to check here to set the editor to notepad, notepad++, etc. unless you really want to use vim.
commit and Further
That was the first change I wanted to make. Remember, it's good practice to commit each time you complete an idea or concept. This change was a complete concept for me, so I committed.
However, there's another issue with the library that I need to resolve as well. So, I'm going to add those changes, and follow the steps again. I make my changes, check the
status, check the
diff to make sure I made the correct changes,
add the file to be committed, compose a short commit message, and
commit my changes.
You can repeat the steps above as many times as you'd like.
Once you've committed all of the changes you intend to make, you're ready to push to your fork.
You've committed your final change, and you're ready to submit your code to the project. This means it's time to push to your fork. When you
push, you're sending the list of commits since the last push to your remote repo. In other words, you're "uploading" your changes to your repo on GitHub. Until you
push, none of your commits show up on GitHub. So think of commits as local save points, and pushes as remote save points. This also means that once you
push, your changes are visible to the public. So
commit as often as you like, but only
push when you're ready for it to be submitted to the project. If you do
push too soon, it's okay though! It happens to all of us. You can always
push again after you do a few more commits.
As usual, first run
status results in
nothing to commit, working tree clean, it means there have been no changes to any files in your repo since the last time you committed. This is the state you want to be in before pushing your changes.
Now, you want to enter the
push command. Remember, when we setup the repo, we aliased it to your GitHub ID so you'd know it's your repo. The
push command consists of the command, your alias, and your branch name. So, enter the following, replacing
yourid with your GitHub ID, and
your-branch-name with the name of your branch:
git push yourid your-branch-name
Excellent! Now you can continue working. Or if you're ready, you can head over to GitHub to prepare to open a pull request.
pushing to the CircuitPython
As we create new releases and begin to work on new versions of CircuitPython, the previous releases are moved to their own branches. In the event that you are adding something to one of the previous versions, the
push command above may fail. Follow the instructions provided in the error message to properly
push to your current working branch. For more details on
push, please see the git push documentation.