start edit history.txt

[gitmagic.git] / vi / history.txt

== Lessons of History ==

A consequence of Git's distributed nature is that history can be edited
easily. Nhưng nếu bạn xáo trộn quá khứ, hãy cẩn thận: only rewrite that part of
history which you alone possess. Just as nations forever argue over who
committed what atrocity, if someone else has a clone whose version of history
differs to yours, you will have trouble reconciling when your trees interact.

Một số nhà phát triển phần mềm quả quyết rằng lịch sử có thể be immutable, warts and all.
Others feel trees should be made presentable before they are unleashed in
public. Git accommodates both viewpoints. Giống như việc nhân bản, tạo nhánh và hòa trộn,
viết lại lịch sử đơn giản chỉ là một quyền mà Git trao cho bạn. It is up to you
to use it wisely.

=== I Stand Corrected ===

Bạn vừa mới commit, nhưng lại ước mình đã gõ những dòng chú thích có nội dung khác phải không? Thế thì hãy chạy:

 $ git commit --amend

để thay đổi chú thích cuối cùng. Bạn giật mình vì quên thêm các tệp tin vào? Chạy lệnh *git add* để
thêm nó vào, và sau đó lại chạy lệnh ở trên.

Bạn muốn thêm vài chỉnh sửa vào lần cuối mình đã commit ư? Thế thì cứ sửa chúng đi và sau đó chạy lệnh:

 $ git commit --amend -a

=== ... And Then Some ===

Let's suppose the previous problem is ten times worse. After a lengthy session you've made a bunch of commits. But you're not quite happy with the way they're organized, and some of those commit messages could use rewording. Then type:

 $ git rebase -i HEAD~10

và and the last 10 commits will appear in your favourite $EDITOR. Một đoạn trích ví dụ:

    pick 5c6eb73 Added repo.or.cz link
    pick a311a64 Reordered analogies in "Work How You Want"
    pick 100834f Added push target to Makefile

Then:

- Remove commits by deleting lines.
- Reorder commits by reordering lines.
- Replace `pick` with:
   * `edit` to mark a commit for amending.
   * `reword` để thay đổi nhật ký message.
   * `squash` to merge a commit with the previous one.
   * `fixup` to merge a commit with the previous one and discard the log message.

Ghi lại và thoát ra. Nếu bạn đánh dấu một lần commit dành cho việc sửa đổi, thế thì
chạy:

 $ git commit --amend

Cách khác, chạy:

 $ git rebase --continue

So commit early and commit often: you can tidy up later with rebase.

=== Local Changes Last ===

You're working on an active project. You make some local commits over time, and
then you sync with the official tree with a merge. This cycle repeats itself a few times before you're ready to push to the central tree.

But now the history in your local Git clone is a messy jumble of your changes and the official changes. You'd prefer to see all your changes in one contiguous section, and after all the official changes.

Đây chính là công việc dành cho lệnh *git rebase* đã được miêu tả ở trên. Trong nhiều trường hợp bạn có thể sử dụng
cờ *--onto* và and avoid interaction.

Also see *git help rebase* for detailed examples of this amazing command. You can split commits. You can even rearrange branches of a tree.

=== Viết Lại Lịch Sử ===

Occasionally, bạn muốn việc quản lý mã nguồn giống việc người ta vẽ quivalent of airbrushing people out
of official photos, erasing them from history in a Stalinesque fashion. Ví
dụ, giả sử chúng ta có ý định phát hành dự án, nhưng lại dibut it involves a file that
phải được giữ bí mật vì lý do nào đó. Có lẽ tôi đã quên khi ghi lại số thẻ tín dụng vào trong một tệp tin
văn bản và ngẫu nhiên nó được thêm vào trong dự án. Việc xóa tệp tin này là
chưa đủ, bởi vì ta có thể đọc nó từ lần commit cũ. Chúng ta phải gỡ bỏ
tệp tin này từ tất cả các lần đã commit:

 $ git filter-branch --tree-filter 'rm top/secret/file' HEAD

Xem *git help filter-branch*, nội dung của nó sẽ thảo luận về ví dụ này và đưa ra
một cách thức nhanh hơn. Đại thể, lệnh *filter-branch* lets you alter large sections of history
chỉ bằng một lệnh đơn.

Afterwards, the +.git/refs/original+ directory describes the state of affairs before the operation. Check the filter-branch command did what you wanted, then delete this directory if you wish to run more filter-branch commands.

Cuối cùng, replace clones of your project with your revised version if you want to interact with them later.

=== Making History ===

[[makinghistory]]
Want to migrate a project to Git? If it's managed with one of the more well-known systems, then chances are someone has already written a script to export the whole history to Git.

Otherwise, look up *git fast-import*, which reads text input in a specific
format to create Git history from scratch. Typically a script using this
command is hastily cobbled together and run once, migrating the project in a
single shot.

Dưới đây là một ví dụ, dán danh sách theo sau đâu vào một tệp tin tạm thời nào đó, chẳng hạn như là `/tmp/history`:
----------------------------------
commit refs/heads/master
committer Alice <alice@example.com> Thu, 01 Jan 1970 00:00:00 +0000
data <<EOT
Initial commit.
EOT

M 100644 inline hello.c
data <<EOT
#include <stdio.h>

int main() {
  printf("Hello, world!\n");
  return 0;
}
EOT


commit refs/heads/master
committer Bob <bob@example.com> Tue, 14 Mar 2000 01:59:26 -0800
data <<EOT
Replace printf() with write().
EOT

M 100644 inline hello.c
data <<EOT
#include <unistd.h>

int main() {
  write(1, "Hello, world!\n", 14);
  return 0;
}
EOT

----------------------------------

Thế thì tạo một kho Git từ thư mục chứa các tệp tin tạm thời này bằng cách gõ:

 $ mkdir project; cd project; git init
 $ git fast-import --date-format=rfc2822 < /tmp/history

Bạn có thể checkout phiên bản cuối của dự án với:

 $ git checkout master .

Lệnh *git fast-export* chuyển đổi bất kỳ một kho chứa nào thành định dạng
phù hợp với lệnh *git fast-import*, whose output you can study for writing exporters,
and also to transport repositories in a human-readable format. Indeed,
these commands can send repositories of text files over text-only channels.

=== Where Did It All Go Wrong? ===

You've just discovered a broken feature in your program which you know for sure was working a few months ago. Argh! Where did this bug come from? If only you had been testing the feature as you developed.

It's too late for that now. However, provided you've been committing often, Git
can pinpoint the problem:

 $ git bisect start
 $ git bisect bad HEAD
 $ git bisect good 1b6d

Git checks out a state halfway in between. Test the feature, and if it's still broken:

 $ git bisect bad

If not, replace "bad" with "good". Git again transports you to a state halfway
between the known good and bad versions, narrowing down the possibilities.
After a few iterations, this binary search will lead you to the commit that
caused the trouble. Once you've finished your investigation, return to your
original state by typing:

 $ git bisect reset

Instead of testing every change by hand, automate the search by running:

 $ git bisect run my_script

Git uses the return value of the given command, typically a one-off script, to
decide whether a change is good or bad: the command should exit with code 0
when good, 125 when the change should be skipped, and anything else between 1
and 127 if it is bad. A negative return value aborts the bisect.

You can do much more: the help page explains how to visualize bisects, examine
or replay the bisect log, and eliminate known innocent changes for a speedier
search.

=== Who Made It All Go Wrong? ===

Like many other version control systems, Git has a blame command:

 $ git blame bug.c

which annotates every line in the given file showing who last changed it, and when. Unlike many other version control systems, this operation works offline, reading only from local disk.

=== Kinh Nghiệm Riêng ===

Trong một hệ thống quản lý mã nguồn tập trung, thay đổi lịch sử là một việc làm
khó khăn, và chỉ thi hành được nếu là người quản trị. Việc nhân bản, tạo nhánh và
trộn không thể thiếu việc truyền thông qua mạng. So are basic operations
such as browsing history, or committing a change. Trong một số hệ thống khác, người dùng
yêu cầu có kết nối mạng chỉ để xem các thay đổi của họ hay mở một tệp tin
để biên tập.

Hệ thống tập trung không cho phép làm việc mà không có mạng, và đòi hỏi cơ sở hạ tầng mạng máy tính
đắt đỏ tốn kém, đặc biệt là khi số nhà phát triển phần mềm tăng lên. Điều quan trọng
importantly, all operations are slower to some degree, usually to the point
where users shun advanced commands unless absolutely necessary. In extreme
cases this is true of even the most basic commands. Khi những người dùng phải chạy các lệnh chạy chậm
commands, hiệu suất bị giảm bởi vì sự gián đoạn trong dây truyền làm việc.

I experienced these phenomena first-hand. Git was the first version control
system I used. I quickly grew accustomed to it, taking many features for
granted. I simply assumed other systems were similar: choosing a version
control system ought to be no different from choosing a text editor or web
browser.

I was shocked when later forced to use a centralized system. A flaky internet
connection matters little with Git, but makes development unbearable when it
needs to be as reliable as local disk. Thêm nữa, I found myself conditioned
to avoid certain commands because of the latencies involved, which ultimately
prevented me from following my desired work flow.

Khi tôi phải chạy những lệnh chậm chạp, việc làm ngắt quãng việc suy nghĩ
dealt a disproportionate amount of damage. Trong khi chờ cho việc truyền thông
với máy chủ hoàn tất, tôi sẽ phải làm một vài thứ gì đó khác để lấp chỗ trống, chẳng hạn như
lấy thư điện tử hay viết tài liệu. Sau một khoảng thời gian tôi quay trở lại nhiệm vụ
chính của mình, lệnh đã hoàn tất từ lâu rồi, và tôi phải lãng phí thêm nhiều thời gian nữa
để nhớ lại xem mình đang làm gì. Con người thường dở khi phải  Humans are bad at context switching.

There was also an interesting tragedy-of-the-commons effect: anticipating
network congestion, nhiều cá nhân riêng lẻ có thể chiếm dụng nhiều lưu lượng mạng hơn cần thiết
trên các tác vụ khác nhau various operations in an attempt to reduce future delays. The combined efforts
intensified congestion, encouraging individuals to consume even more bandwidth
next time to avoid even longer delays.