Starting from:
$45
CPE2600 Lab 8 -Git Some More Solution
Topical Concepts
GitHub README and Markdown
“README” files have a long history in software development. Since ‘C’ programs have been historically distributed in source form, the README (or README.txt or readme.txt) files are included with the distribution and contain instructions for building the program, operator instructions, and known limitations and bugs (errata). README files are typically plain text files easily readable on any system. GitHub and other providers of git remote service embrace this tradition and if a README file is present in a repository, the web-based repository viewer will display the README file.
Source Version Control – Next Steps
Periodic Commits
Ideally, as you continue to develop, you will commit changes to the git repository periodically. You can view a history of those commits with the command git log. Example:
We can see each commit’s comments along with a timestamp and a hash of the repository at the time of the commit.
We can also, change our “view” to any of these versions of the repository. Now, some care must be exercised.
Temporary View - git checkout
The command git checkout <commit hash> can be issued to revert the working directory to the state of a previous commit.
So given these cautions, why are we doing this. Again, maybe just to look around – that is see the entire project at a previous state. Perhaps you added a feature in future commits that is not working properly, so you want to go back to a previous working state. Despite the caution not to make changes, this is your full working directory – you can still build and run or debug the program.
You can return to the most current commit with git checkout main for this example.
Tagging Commits
There are two types of tags. An “annotated tag” is somewhat analogous to a commit and stores a timestamp, message, and information about the tagger. This is the type of tag you would use for a release. A “lightweight tag” is really just an alias to an existing commit and not as versatile. Any future discussion or usage of tags will be referring to annotated tags.
Creating a tag is much like a commit, just a different command. For example:
git tag -a v1.0 -m “Major Release”
will create an annotated tag (-a) named v1.0 with message “Major Release.”
One slight complication is that tags are not pushed to remote with git push like normal commits. You have to explicitly list the tag(s) you wish to push or --tags to commit all. Example:
git push --tags
Tags can be used with the ‘checkout’ command to set the working directory to the exact set of source that was present when tagged. Now, the purpose of checkout should be clear.
Note the same ‘detached HEAD’ state and the same cautions as before.
Since you have a record of all commits, it is easy enough apply tags later. Simply add the hash for the commit you wish to tag.
git tag -a v0.1 -m "Minor Release" 59f6
In this example, commit with a hash that starts with 59f6 would be tagged instead of HEAD.
Branching and Merging
This will be discussed in a future Lab.
The Exercise
Overview
For your current lab exercise, Vector Calculator Updates, you should have been committing update to your repository periodically. When you are finished with various updates, you will be tagging the new “release” as well as tagging your previous “release.” In addition, you will be adding a README.md file to your repository.
Specific Instructions
1. Add a README.md file to your repository. You should already know how to add new files to the repository. In the README.md file, you should provide basic instructions typical of a README file. Items to include:
a. A brief description of the program and how it works.
b. How to build the program
c. How to run the program – available command line options
d. A list of commands supported by the program
e. A short description of how your program uses dynamic memory (ok, not typical – think lab report…)
Much of this information might already be embedded in your program – no problem if you wish to copy-andpaste to save some typing.
Note, VS Code will happily render Markdown, so it is easy to write your README.md in VS Code and expect it to look good in GitHub. Alternatively, take a stab in your text editor, commit the file and push to remote. You can further edit within the GitHub website to clean up any malfunctioning Markdown.
2. When your updates are complete and ready to demo, tag your repo v2.0. Make sure the README.md is part of the repo at this time. Be sure to push all commits and tags to remote.
3. After demoing the update, use git checkout to revert to your previous version that was demoed prior to adding dynamic memory and file i/o. Build and verify proper operation. Tag this commit with v1.0. Push all commits and tags. Also be sure to return HEAD to the latest commit at some point.
Deliverable
Provide a lab report showing screen shots of the exercises in the lab. A demo checkoff of your repository will be completed in lab. I will expect to find a useful README.md as described above and at least two tags that will correspond to the initial Vector Calculator assignment and the Vector Calculator Updates.
GitHub README and Markdown
“README” files have a long history in software development. Since ‘C’ programs have been historically distributed in source form, the README (or README.txt or readme.txt) files are included with the distribution and contain instructions for building the program, operator instructions, and known limitations and bugs (errata). README files are typically plain text files easily readable on any system. GitHub and other providers of git remote service embrace this tradition and if a README file is present in a repository, the web-based repository viewer will display the README file.
Source Version Control – Next Steps
Periodic Commits
Ideally, as you continue to develop, you will commit changes to the git repository periodically. You can view a history of those commits with the command git log. Example:
We can see each commit’s comments along with a timestamp and a hash of the repository at the time of the commit.
We can also, change our “view” to any of these versions of the repository. Now, some care must be exercised.
Temporary View - git checkout
The command git checkout <commit hash> can be issued to revert the working directory to the state of a previous commit.
So given these cautions, why are we doing this. Again, maybe just to look around – that is see the entire project at a previous state. Perhaps you added a feature in future commits that is not working properly, so you want to go back to a previous working state. Despite the caution not to make changes, this is your full working directory – you can still build and run or debug the program.
You can return to the most current commit with git checkout main for this example.
Tagging Commits
There are two types of tags. An “annotated tag” is somewhat analogous to a commit and stores a timestamp, message, and information about the tagger. This is the type of tag you would use for a release. A “lightweight tag” is really just an alias to an existing commit and not as versatile. Any future discussion or usage of tags will be referring to annotated tags.
Creating a tag is much like a commit, just a different command. For example:
git tag -a v1.0 -m “Major Release”
will create an annotated tag (-a) named v1.0 with message “Major Release.”
One slight complication is that tags are not pushed to remote with git push like normal commits. You have to explicitly list the tag(s) you wish to push or --tags to commit all. Example:
git push --tags
Tags can be used with the ‘checkout’ command to set the working directory to the exact set of source that was present when tagged. Now, the purpose of checkout should be clear.
Note the same ‘detached HEAD’ state and the same cautions as before.
Since you have a record of all commits, it is easy enough apply tags later. Simply add the hash for the commit you wish to tag.
git tag -a v0.1 -m "Minor Release" 59f6
In this example, commit with a hash that starts with 59f6 would be tagged instead of HEAD.
Branching and Merging
This will be discussed in a future Lab.
The Exercise
Overview
For your current lab exercise, Vector Calculator Updates, you should have been committing update to your repository periodically. When you are finished with various updates, you will be tagging the new “release” as well as tagging your previous “release.” In addition, you will be adding a README.md file to your repository.
Specific Instructions
1. Add a README.md file to your repository. You should already know how to add new files to the repository. In the README.md file, you should provide basic instructions typical of a README file. Items to include:
a. A brief description of the program and how it works.
b. How to build the program
c. How to run the program – available command line options
d. A list of commands supported by the program
e. A short description of how your program uses dynamic memory (ok, not typical – think lab report…)
Much of this information might already be embedded in your program – no problem if you wish to copy-andpaste to save some typing.
Note, VS Code will happily render Markdown, so it is easy to write your README.md in VS Code and expect it to look good in GitHub. Alternatively, take a stab in your text editor, commit the file and push to remote. You can further edit within the GitHub website to clean up any malfunctioning Markdown.
2. When your updates are complete and ready to demo, tag your repo v2.0. Make sure the README.md is part of the repo at this time. Be sure to push all commits and tags to remote.
3. After demoing the update, use git checkout to revert to your previous version that was demoed prior to adding dynamic memory and file i/o. Build and verify proper operation. Tag this commit with v1.0. Push all commits and tags. Also be sure to return HEAD to the latest commit at some point.
Deliverable
Provide a lab report showing screen shots of the exercises in the lab. A demo checkoff of your repository will be completed in lab. I will expect to find a useful README.md as described above and at least two tags that will correspond to the initial Vector Calculator assignment and the Vector Calculator Updates.
1 file (1.2MB)
