2. Project management¶
This week was quite hard for me as it was the first time I have ever encountered:
- the Terminal
- a VCS
- web develpment
Antonio, my mentor, had helped me setting up Homebrew.
I was very satisfied of having been able to understand th geometry of a VCS and the workflow needed to operate it. I was happy aswell to figure out that markdown was not hard to understand at all.
I proceded by:
- installing latest Python version via terminal
- generate SSH key via terminal, and pair it
- clone my repo
- install mkDocs
- work on my local repo
- preview my site via terminal
- add, commit, push
Website¶
Since I was new to all this I decide to start building the website with the mkDocs format theme provided to us.
I installed mkDocs on my laptop via terminal, initialised my repo, installed Python to be abe to run ‘mk docs serve.
I began by updating the directories and files that were already there, I then added parts I needed to the wesite.
It’s possible to see the command lines and markdown language I learnt in my Additional Documentation page.
Git Setup¶
First thing first, one has to switch shell in their terminal:
- in my case (Catalina), the first shell was Zsh, I had to switch to bash
- you can check your shell by typing ‘$ echo $SHELL’
- you can change you shell by typing ‘ $ chsh -s /bin/bash’
After that you can install git using Homebrew. To do so one has to type ‘$ brew install git’. You can also check wether git is already installed, it’s version and if it needs upgrade:
- ‘which git’ to check if executable git is present
- ‘git –version’ to check if it’s a recent enough version of git
- ‘brew upgrade git’ to run git updates
Git configuration¶
After installing git, the next step is configurate the program. The next lines to by typed in bash are one-off commands onlly done to setup git.
In order to identify yourself as author of changes in vcs you have to log in as a user by typing the following lines.
’$ git config –global user.name “User Name”‘ ‘$ git config –global user.email e-mail address‘
Then one can type ‘$ git config –global init.defaultBranch main’ to set the current git directory as main branch.
Once a directory is made (using ‘mkdir’) it can be initialized as a git repo by using ‘git init’.
To start working locally on a remote repo, one has to generate a SSH key (as shown above / ‘ssh-keygen -t key type -C comment). The key is then added in the git User Setting page, under SSH Keys.
Remote -> Local¶
Once git is installed, a directory made, a repo initialized, one can start actually working on VCS.
To copy in local your repository, and start tracking uploads and changes from local to remote one has to type ‘git clone’ followed by the URL of the needed repositorty.
- To copy remote branch one types ‘git checkout –track remote branch’.
- To track remote changes ‘git fetch remote branch’.
- To merge remote change to local repo ‘git pull’.
Local -> Remote¶
Once one has made changes to files that will be uploaded to the repo, these are the steps they have to follow:
- ‘git status’ shows the differences in between the local and remote directories.
- ‘git add -A’; the -A option adds all files to the commit queue, I mainly used this, but one can choose different options such as -p ‘file name’ for single file changes (in the screenshot I repeated git status to show how the missing files got added to the commit queue)
- ‘git commit -m “message”’ to commit all changes to the repo
- ‘git push’ to upload committed changes to remote repo
mkDocs Local Server¶
In order to preview one’s markdown website before pushing it to git, once can move in bash to the website directory (‘ cd directory’) the they can easily type ‘mkdocs serve’, an address will be generated, one can copy\paste that address in their browser and locally visualise the website. Screenshot regarding this is just below, in the Screnshot section.
Notes¶
In this notes I outlined:
- basic git actions
- workflow trees to operate Git
- git setup steps
- basic repo architecture
- project layout
Current State¶
I also drew a schematic to help me visualise the history of my local and remote repo.
In nR and nL the n(umber) stand for the repo version, the R stands for remote, the L stand for local.
The second R folder called nR2, is a second remote folder that Antonio cloned on his computer when showing how to operate terminal via Visual Studio code.
This history three is missing 1 step of adding, committing and pushing happed earlier today, so it’s notfully up to date, but it’s showing my repo history up to the 2nd of February.
Screenshots¶
I used Visual Studio Code to edit the .md files that constitute my website at the moment.
SSH Key installation via terminal.
Add\commit\push\git status workflow example. During last week I did multiple of these.
Commit log.
mkDocs local server website preview.
Useful links¶
Task List¶
- [x] Made website
- [x] Document how
- [x] Introduce yourself
- [x] Documented git steps
- [x] Push to class archive
- [x] Upload student agreement