Przeczytaj mnie…

with Brak komentarzy

To już chyba będzie na razie ostatnia część o GIT-cie. Część trzecia. O ważnym pliku, jaki musi znaleźć się w projekcie na GITHUB-e oraz o innych plikach, o których warto poczytać.

Readme.md

To opis całego projektu. Ten plik to zalążek dokumentacji. Można go dodać już na początku projektu – wraz z tworzonym repozytorium. Informuje innych, o czym jest projekt, co z nim mogą zrobić i jak korzystać. Jest pierwszym elementem, jaki zobaczą, wchodząc do repozytorium. Musi zawierać podstawowe informacje o nim. To taka reklama Waszego kodu. 😉

Warto wyćwiczyć sobie nawyk zamieszczania zgrabnego pliku README. Dlaczego? Właśnie dlatego, aby był to Twój nawyk, poza tym, jak wspomniałam nie raz GITHUB to takie Twoje portfolio, wizytówka. Kiedy będziesz szukać pracy, rekruterzy IT szukają swoich kandydatów zwłaszcza na GITHUB-e, patrzą jakie projekty tam się znajdują, jak napisane i, czy działasz zgodnie z ogólnie przyjętymi zasadami.

Co to za rozszerzenie pliku .md ? To od słówka markdown – język znaczników, który służy do formatowania tekstów. Może wygląda groźnie, ale jest całkowicie prosty. Więcej na temat tego języka znajdziecie na Wiki.
Oczywiście na GITHUB-e znajdziecie pomocną stronkę – o tu, jak posługiwać się nim w pliku README.
Edytor online tego języka znajdziecie na stronie https://dillinger.io/


Gotowy szablon wraz z wszystkimi nagłówkami, spisem treści, informacjami co i jak wpisać znajdziecie o tu.
Kopiując wersję RAW do swojego pliku Readme.md możecie spokojnie edytować szablon.

Nad czym warto się zastanowić i co wpisać? Między innymi nad:

  • Tytuł, śródtytuły – świetnie robi się wtedy spis treści z linkami do poszczególnych części dokumentu, 
  • Wprowadzenie – cel projektu, po  go w ogóle robisz? Uczysz się nowej technologii? Chcesz przećwiczyć tworzenie pewnych schematów?
  • Technologie – czego używasz? Jakich języków lub frameworków, bibliotek? Wersje danych technologii też warto wpisać. Dlaczego takich języków się używa, a nie innych? 
  • Uruchomienie – jak uruchomić projekt? Jakieś szczególne środowisko jest potrzebne? Wymagania sprzętowe.

Można dodać również:

  • Spis treści – z linkami odsyłającymi,
  • Ilustracje – zawsze lepiej coś pokazać na obrazku jak coś działa, a nasz mózg lubi obrazy, lepiej je zapamiętuje. Ilustrowana instrukcja obsługi? Czemu nie?

    Pomocny będzie schemat:
    ![tekst alternatywny](ścieżka/do/pliku) – gdy zdjęcie/ilustracja jest w folderze na GITHUB-e
    lub
    ![tekst alternatywny](URL/do/pliku) – gdy używamy zdjęcia ogólnodostępnego
  • Funkcjonalności – jakie funkcje spełnia projekt? Jakie opcje są dostępne?
  • Przykłady użycia – schemat, jaki trzeba użyć, bo projekt zadziałał,
  • Status – projekt jeszcze się rozwija? Czy to już skończona historia?
  • Źródła – z jakich źródeł korzystaliśmy? Jakie tutoriale były pomocne? Gdzie szukaliśmy inspiracji do rozwiązania jakiegoś problemu?
  • Inne informacje – informacje o autorze, linki do social mediów, strona www autora, na jakiej zasadzie można używać Twojego kodu itp.


.gitignore

To plik konfiguracyjny wskazujący na pliki, które ma ignorować GIT podczas commitowania. Dlaczego? Aby sprawniej się pracowało. Używamy go, gdy nie chcemy czegoś w repozytorium, np. plik, który powstaje po kompilacji css do sass.  Można takie pliki również wykluczyć – Exclude .
Jak stworzyć taki plik .gitignore? Są dwie możliwości. Pierwsza z nich jest banalnie prosta i polega na zaznaczeniu tej opcji przy tworzeniu repozytorium.
Druga wymaga trochę więcej pracy i kodu. Znalazłam prostą instrukcję, więc nie będę jej przepisywać. Znajduje się ona na blogu Keep Calm And Try Coding. Kreator, o którym wspomina autorka, można znaleźć poniżej:

Kreator pliku .gitignore.

Co to u licha jest?

.gitkeep

Wskazuje na foldery również puste, które powinny być wysłane do repozytorium. Niestety, jeśli folder jest pusty, GIT go ignoruje domyślnie. Aby temu przeciwdziałać, tworzymy plik o nazwie .gitkeep w danym folderze – nie jest on już pusty i wszystko gra i buczy. Sukces! Proste i logiczne. Nazwa tego pliku wskazuje na to, że nie jest to żaden kod czy inna ważna sprawa. Można ją zignorować.

Co ciekawe można ten plik wykorzystać nawet w takiej sytuacji, gdy chcemy wysłać do repozytorium sam folder bez zawartości. Wymaga to utworzenie .gitkeep w danym folderze i dopisania kodu do pliku .gitignore

#ignore files in folder
foo/*

#but keep the folder
!foo/.gitkeep

Takie rozwiązanie znalazła o tu


Pliki, o których warto jeszcze sobie doczytać to z pewnością: .gitconfig oraz .gitattributes.
Ten pierwszy plik odpowiada za konfigurację GIT-a (w nim wpisywaliśmy nasz email i nasze dane). Można o nim poczytać ciut więcej o tu.
Drugi z kolei to plik, dzięki któremu używając atrybutów, możesz np. określić oddzielne strategie scalania dla pojedynczych plików lub katalogów w projekcie, powiedzieć Git, jak odróżnić pliki nietekstowe, lub zmienić zawartość filtra Git, zanim zaczniesz go sprawdzać lub usuwać z Git. Więcej informacji na ten temat znalazłam o tu.

To by było na tyle tym razem. Jak zwykle chciałam napisać tylko podstawy podstaw, a już wychodzi mi ponad 700  słów… Będzie część czwarta. Z komendami, które przydają się w codziennym użytkowaniu GIT-a.

I jeszcze jedna fajna rzecz. Maciej Aniserowicz tworzy “kurs Gita”. Można zapisać się na listę mailingową. To kurs płatny, lecz z pewnością pieniądze będą bardzo dobrze wydane. 🙂 Maciej prowadzi bloga i vloga devstyle.pl

Zapisz się na Newsletter i pobierz prezent powitalny.

Co miesiąc znajdziesz miły list w skrzynce e-mail ... A już dziś śliczna jesienna zakładka do książek oraz tapeta na pulpit może być Twoja.

Wyrażam zgodę na przekazywanie moich danych osobowych MailChimp ( more information )

Twój e-mail będzie chroniony. W każdym momencie będziesz mógł/mogła się wypisać.

Follow Danuta:

Blogująca mama dwóch chłopców. Ciągle ucząca się i poszukująca pomysłu na siebie. Obecnie pogłębiająca tajniki programowania.

Latest posts from

Zostaw komentarz