eblancoga/repodemo

Material to learn how to manage GitHub repositories

README of repoDemo

Enrique Blanco @ Luciano Di Croce (CRG, 2013-2022)

WEB part of the work: Please use Firefox, Chrome or other internet browser in this block

(0) Explore the Github repository management documentation:

https://docs.github.com/en https://github.com/git-guides/

(1) Create your user account in GitHub (username "eblancoga" for this tutorial):

https://github.com/signup

(2) Generate a token for your authentification in future operations:

https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

NOTE: Once you get the token, store it in a safe place for the future)

(3) Create a New repository (empty) in your GitHub account: ("repoDemo" is the name that will be used here)

https://github.com/new

NOTES: options of creation in the GitHub web

• we will ommit the automatical creation of the README
• .gitignore file is not necessary now
• please, choose an open-software license to distribute your code (e.g. GPL)

RESULT: see screenshots in folder1/demoRepo1.png and folder1/demoRepo2.png

MORE NOTES:

• Branches are "versions/development lines" of your project that are assigned a name

• README is the file informing/introducing your software/project to the community

https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes

• .gitignore files are empty files placed inside folders that should not be included into any future add/commit operations. This is very useful when your code contains empty folders (to be distributed) that after during installation in the computer of the user will populated by new files generated by makefiles, compilations, etc. Otherwise, empty folders are removed

https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files

RESULT: see screenshot in folder1/demoRepo3.png: the new repo "eblancoga/repoDemo" has been successfuly created (empty). It contains a single branch named "main")

Terminal part: how to connect your repo in GitHub with your command line interface (CLI) (bash, terminal)

(4) Clone (get a copy) of your new repo in your current working directory:

eblanco:> git clone https://github.com/eblancoga/repoDemo

  Cloning into 'repoDemo'...
  remote: Enumerating objects: 3, done.
  remote: Counting objects: 100% (3/3), done.
  remote: Compressing objects: 100% (2/2), done.
  remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
  Unpacking objects: 100% (3/3), 12.41 KiB | 160.00 KiB/s, done.

eblanco:> cd repoDemo

(5) The content is an exact copy of our GitHub repository:

eblanco:> ls

LICENSE

eblanco:> ls -a

.  ..  .git  LICENSE

eblanco:> ls -a .git/

.  ..  branches  config  description  HEAD  hooks  index  info	logs  objects  packed-refs  refs

NOTE: the .git/ subfolder contains internal info for managing the git features

(6) Check the status of this copy:

eblanco:> git status

On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean

NOTE: The "git status" command display information about changes that eventually have been done in your current repo copy (in comparison to the GitHub copy of the repo, which is the consolidated one)

(7) Consolidate file changes in our local copy and into the GitHub copy: add/commit/push

NOTE: The sequence of typical operations when working with repos:

• you make changes in your local copy (new files, new folders, edit files, ...)
• you "add" changes to be commited
• you "commit" changes to be integrated in your local copy
• you "push" commited changes to be incorporated in your github official repo

NOTE: First, we will generate a new file (README) to be incorporated into the GitHub copy:

eblanco:> cat > README

This is the initial version of this demo repository for GitHub (press Ctrl+D now)

eblanco:> cat README

This is the initial version of this demo repository for GitHub (press Ctrl+D now)

NOTE: We can check the new status (changes to be added = new file README)

eblanco:> git status

On branch main
Your branch is up to date with 'origin/main'.
Untracked files:
(use "git add <file>..." to include in what will be committed)
README
nothing added to commit but untracked files present (use "git add" to track)

NOTE: The Add command prepares each change/modification we have done in our repo copy to be consolidated

eblanco:> git add .

(options for adding files:

% git add .

% git add --all

% git add filename)

On branch main
Your branch is up to date with 'origin/main'.
Changes to be committed:
(use "git restore --staged <file>..." to unstage)
new file:   README

NOTE: The Commmit command executes the changes defined by the previous Add and our local repo is updated now (-m is the option to include a short message to describe the main changes incorporated now)

eblanco:> git commit -m "Initial version of our project"

[main d383291] Initial version of our project
1 file changed, 1 insertion(+)
create mode 100644 README

eblanco:> git status

On branch main
Your branch is ahead of 'origin/main' by 1 commit.
(use "git push" to publish your local commits)
nothing to commit, working tree clean

NOTE: To update the remote repository in GitHubm we will push this change (previously committed)

eblanco:> git push

Username for 'https://github.com': eblancoga
Password for 'https://[email protected]': 
Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 361 bytes | 361.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To https://github.com/eblancoga/repoDemo
9f7119c..d383291  main -> main

eblanco:> git status

On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean

RESULT: see screenshot in folder1/demoRepo4.png: our repo includes the README file, which is automatically shown.

(8) Consolidate new folders in our local copy and into the GitHub copy

eblanco:> mkdir folder1 folder2

eblanco:> git status

On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean

NOTE: New (empty) folders are ignored for the commits

eblanco:> touch folder1/.gitignore

eblanco:> touch folder2/.gitignore

NOTE: We should generate the .gitignore empty file into each folder to ensure the new folders are detected

eblanco:> git status

On branch main
Your branch is up to date with 'origin/main'.
Untracked files:
(use "git add <file>..." to include in what will be committed)
folder1/
folder2/
nothing added to commit but untracked files present (use "git add" to track)

eblanco:> git add .

eblanco:> git commit -m "Adding two new folders"

[main 5a990f6] Adding two new folders
2 files changed, 0 insertions(+), 0 deletions(-)
create mode 100644 folder1/.gitignore
create mode 100644 folder2/.gitignore

eblanco:> git push

Username for 'https://github.com': eblancoga
Password for 'https://[email protected]': 
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (4/4), 366 bytes | 366.00 KiB/s, done.
Total 4 (delta 0), reused 0 (delta 0)
To https://github.com/eblancoga/repoDemo
d383291..5a990f6  main -> main

eblanco:> git status

On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean

RESULT: see screenshot in folder1/demoRepo5.png: our repo includes the two new folders.

(9) Populating the repo (folders): example1

NOTE: We copy/move any file of our computer into our local copy of our repo and perform add/commit/push to reflect these changes in the remote copy of the repo

NOTE: Example1, images of the tutorial that were initially stored in my Desktop

eblanco:> cp ~/Desktop/*.png folder1/

eblanco:> git status

On branch main
Your branch is up to date with 'origin/main'.
Untracked files:
(use "git add <file>..." to include in what will be committed)
folder1/repoDemo1.png
folder1/repoDemo2.png
folder1/repoDemo3.png
folder1/repoDemo4.png
folder1/repoDemo5.png
nothing added to commit but untracked files present (use "git add" to track)

eblanco:> git add .

eblanco:> git commit -m "Adding screenshots of the tutorial"

[main d9e119c] Adding screenshots of the tutorial
5 files changed, 0 insertions(+), 0 deletions(-)
create mode 100755 folder1/repoDemo1.png
create mode 100755 folder1/repoDemo2.png
create mode 100755 folder1/repoDemo3.png
create mode 100755 folder1/repoDemo4.png
create mode 100755 folder1/repoDemo5.png

eblanco:> git push

Username for 'https://github.com': eblancoga
Password for 'https://[email protected]': 
Enumerating objects: 10, done.
Counting objects: 100% (10/10), done.
Compressing objects: 100% (8/8), done.
Writing objects: 100% (8/8), 198.58 KiB | 4.84 MiB/s, done.
Total 8 (delta 0), reused 0 (delta 0)
To https://github.com/eblancoga/repoDemo
5a990f6..d9e119c  main -> main

RESULT: see screenshot repoDemo6.png

(10) Populating the repo (folders): example2

NOTE: We copy/move any file of our computer into our local copy of our repo and perform add/commit/push to reflect these changes in the remote copy of the repo

NOTE: Example2, full source code distribution of a C program to perform the JOIN of 2 files over any platform

eblanco:> cp -rp ~/Desktop/JoinC folder2/ (make a copy of the code here, no modifications are necessary over your code)

eblanco:> ls -R folder2/*

folder2/JoinC:
bin  include  Makefile	objects  src
folder2/JoinC/bin:
folder2/JoinC/include:
joinc.h
folder2/JoinC/objects:
folder2/JoinC/src:
account.c     GetFileSize.c  Output.c			  ProcessFullGenesetAverageGenes.c  readargv_joinc.c  RequestMemory.c
Dictionary.c  joinc.c	     ProcessFullGenesetAverage.c  ProcessFullGeneset.c		    ReadGeneset.c

NOTE: Users will get a copy of this folder, run the Makefile and will populate the bin/ and objects/ (empty) folders in their local copy

eblanco:> git status

On branch main
Your branch is up to date with 'origin/main'.
Untracked files:
(use "git add <file>..." to include in what will be committed)
folder2/JoinC/
nothing added to commit but untracked files present (use "git add" to track)

eblanco:> git add .

eblanco:> git commit -m "Adding the source code of the JoinC program"

[main 28c39a2] Adding the source code of the JoinC program
13 files changed, 1611 insertions(+)
create mode 100755 folder2/JoinC/Makefile
create mode 100755 folder2/JoinC/include/joinc.h
create mode 100755 folder2/JoinC/src/Dictionary.c
create mode 100755 folder2/JoinC/src/GetFileSize.c
create mode 100755 folder2/JoinC/src/Output.c
create mode 100755 folder2/JoinC/src/ProcessFullGeneset.c
create mode 100755 folder2/JoinC/src/ProcessFullGenesetAverage.c
create mode 100755 folder2/JoinC/src/ProcessFullGenesetAverageGenes.c
create mode 100755 folder2/JoinC/src/ReadGeneset.c
create mode 100755 folder2/JoinC/src/RequestMemory.c
create mode 100755 folder2/JoinC/src/account.c
create mode 100755 folder2/JoinC/src/joinc.c
create mode 100755 folder2/JoinC/src/readargv_joinc.c

eblanco:> git status

On branch main
Your branch is ahead of 'origin/main' by 1 commit.
(use "git push" to publish your local commits)
nothing to commit, working tree clean

eblanco:> git push

Username for 'https://github.com': eblancoga
Password for 'https://[email protected]': 
Enumerating objects: 21, done.
Counting objects: 100% (21/21), done.
Compressing objects: 100% (18/18), done.
Writing objects: 100% (19/19), 13.51 KiB | 384.00 KiB/s, done.
Total 19 (delta 7), reused 0 (delta 0)
remote: Resolving deltas: 100% (7/7), completed with 1 local object.
To https://github.com/eblancoga/repoDemo
d9e119c..28c39a2  main -> main

eblanco:> git status

On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean

RESULT: see screenshot repoDemo7.png

NOTE: Two folders are empty (bin/ and objects/). Use the .gitignore files to add them as well

eblanco:> touch folder2/JoinC/bin/.gitignore

eblanco:> touch folder2/JoinC/objects/.gitignore

eblanco:> git add .

eblanco:> git commit -m "Adding the source code of the JoinC program"

[main f520289] Adding the source code of the JoinC program
 2 files changed, 0 insertions(+), 0 deletions(-)
create mode 100644 folder2/JoinC/bin/.gitignore
create mode 100644 folder2/JoinC/objects/.gitignore

eblanco:> git push

Username for 'https://github.com': eblancoga
Password for 'https://[email protected]': 
Enumerating objects: 8, done.
Counting objects: 100% (8/8), done.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (5/5), 537 bytes | 134.00 KiB/s, done.
Total 5 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To https://github.com/eblancoga/repoDemo
28c39a2..f520289  main -> main

RESULT: see screenshot repoDemo8.png

(11) Generating a nice version of the README (using README.md, markdown)

NOTE: I've edited a README.md file here. Please, type more README.md in your terminal to see the content and compare it with the actual visualization in the GitHub repository

eblanco:> mv README README.md

eblanco:> git status

On branch main
Your branch is up to date with 'origin/main'.
Changes not staged for commit:
(use "git add/rm <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
deleted:    README
Untracked files:
(use "git add <file>..." to include in what will be committed)
README.md
no changes added to commit (use "git add" and/or "git commit -a")

eblanco:> git add .

eblanco:> git commit -m "Updating the README using markdown (md)"

[main dbad0c7] Updating the README using markdown (md)
2 files changed, 48 insertions(+), 1 deletion(-)
delete mode 100644 README
create mode 100644 README.md

eblanco:> git push

Username for 'https://github.com': eblancoga
Password for 'https://[email protected]': 
Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 1.15 KiB | 1.15 MiB/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To https://github.com/eblancoga/repoDemo
b1c4f52..dbad0c7  main -> main

RESULT: see screenshot repoDemo9.png

(12) Copy and paste this text explaining GitHub in 12 steps into our README.md

(previous README.md format tricks are shown at the end) (current state of the repo right now)

(13) MarkDown format tricks for writing READMEs

enrique.blanco at crg.eu

NUMERICAL LIST OF ITEMS

1. Item 1
2. Item 2
3. Item 3
4. ...

1. Item1

Adding a link to http://ldicrocelab.crg.es

Adding a link with name to SAMTools in C

Type code statements for displaying code and use tabulators for blocks of code:

> make all
***** Step 1. Building the CRAM library           *****
gcc  -c -I./include -O2 -D_FILE_OFFSET_BITS=64 -D_LARGEFILE64_SOURCE -D_CURSES_LIB=1 ./src/cram/cram_codecs.c -o ./objects/cram/cram_codecs.o
(...)
***** [OK] CRAM library sucessfully generated     *****

LIST OF BULLETS

• Item 1
• Item 2
• ...

TABLES

Command	Description
buildChIPprofile	generate sequencing data profiles for genome browser visualization.
combineChIPprofiles	combine two genome-wide sequencing data profiles.
combineTSSmaps	produce heatmaps of sequencing signal intensities from 2 samples around the TSS.

About Us

Our lab is focused on the role of multiple epigenetic components (such as histone marks and Polycomb proteins) that govern the development in mouse embryonic stem cells and can be involved in the context of cancer as well.

WEBSITE TWITTER

END of README